Update Javadoc for fireTestSuiteStarted(), fireTestSuiteFinished(),

testSuiteStarted() and testSuiteFinished() to make it clear that
not all runners call these methods, but runners that call
the started methods should also call the finished methods.

Closes #1118

Author: kcooney

src/main/java/org/junit/runner/notification/RunListener.java

@@ -70,7 +70,14 @@ public void testRunFinished(Result result) throws Exception {
     }
 
     /**
-     * Called when a test suite is about to be started.
+     * Called when a test suite is about to be started. If this method is
+     * called for a given {@link Description}, then {@link #testSuiteFinished(Description)}
+     * will also be called for the same {@code Description}.
+     *
+     * <p>Note that not all runners will call this method, so runners should
+     * be prepared to handle {@link #testStarted(Description)} calls for tests
+     * where there was no cooresponding {@code testSuiteStarted()} call for
+     * the parent {@code Description}.
      *
      * @param description the description of the test suite that is about to be run
      *                    (generally a class name)
@@ -81,6 +88,8 @@ public void testSuiteStarted(Description description) throws Exception {
 
     /**
      * Called when a test suite has finished, whether the test suite succeeds or fails.
+     * This method will not be called for a given {@link Description} unless
+     * {@link #testSuiteStarted(Description)} was called for the same @code Description}.
      *
      * @param description the description of the test suite that just ran
      * @since 4.13

src/main/java/org/junit/runner/notification/RunNotifier.java

@@ -106,7 +106,10 @@ protected void notifyListener(RunListener each) throws Exception {
     }
 
     /**
-     * Invoke to tell listeners that a test suite is about to start.
+     * Invoke to tell listeners that a test suite is about to start. Runners are strongly
+     * encouraged--but not required--to call this method. If this method is called for
+     * a given {@link Description} then {@link #fireTestSuiteFinished(Description)} MUST
+     * be called for the same {@code Description}.
      *
      * @param description the description of the suite test (generally a class name)
      * @since 4.13