RFR: [16,test,docs] JDK-8247760 Improve documentation for javadoc.tester.JavadocTester

[Pavel Rappo]

> On 17 Jun 2020, at 19:19, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Please review some updates to the doc comments in JavadocTester,
> to better document the use of the starting/pass/fail methods.
> 
> -- Jon
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8247760
> Webrev: http://cr.openjdk.java.net/~jjg/8247760/webrev.00/

That patch looks good. I applied it and then fixed a few other problems.
Would you consider this resulting patch? Thanks.

diff --git a/test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java b/test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java
--- a/test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java
+++ b/test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java
@@ -62,7 +62,7 @@
  * <p>
  * Tests are typically written as subtypes of JavadocTester, with a main
  * method that creates an instance of the test class and calls the runTests()
- * method. The runTests() methods calls all the test methods declared in the class,
+ * method. The runTests() method calls all the test methods declared in the class,
  * and then calls a method to print a summary, and throw an exception if
  * any of the test methods reported a failure.
  *
@@ -111,7 +111,7 @@
  * <p>
  * If javadoc is run more than once in a test method, you can compare the
  * results that are generated with the diff method. Since files written by
- * javadoc typically contain a timestamp, you may want to use the -notimestamp
+ * javadoc typically contain a timestamp, you may want to use the {@code -notimestamp}
  * option if you are going to compare the results from two runs of javadoc.
  *
  * <p>
@@ -122,10 +122,11 @@
  * on each file in turn with the string to be checked.
  *
  * <p>
- * You can also write you own custom check methods, which can use
- * readFile to get the contents of a file generated by javadoc,
- * and then use pass(...) or fail(...) to report whether the check
- * succeeded or not.
+ * You can also write your own custom check methods. After any setup or
+ * argument checking, the method should call {@code checking(...)},
+ * and then eventually call either {@code passed(...)} or {@code failed(...)}
+ * to report whether the check succeeded or not.
+ * Use {@code readFile} to get the contents of a file generated by javadoc.
  *
  * <p>
  * You can have many separate test methods, each identified with a @Test
@@ -573,7 +574,8 @@
      * The structure is is printed in plain text to the main output stream.
      * No errors are reported (unless there is a problem reading a file)
      * but missing headings are noted within the output.
-     * @params the files
+     *
+     * @param paths the files
      */
     public void showHeadings(String... paths) {
         ShowHeadings s = new ShowHeadings(out, this::readFile);
@@ -813,26 +815,64 @@
         }
     }
 
+    /**
+     * Starts a check.
+     *
+     * <p>This method should be called before subsequently calling {@code pass(...)}
+     * or {@code fail(...)}.
+     *
+     * @param message a short description of the check
+     */
     protected void checking(String message) {
         numTestsRun++;
         javadocTestNum++;
         print("Starting subtest " + javadocRunNum + "." + javadocTestNum, message);
     }
 
+    /**
+     * Concludes a check for a file, reporting that the check succeeded.
+     *
+     * <p>This method should be called after previously calling {@code checking(...)}.
+     *
+     * @param file the file that was the focus of the check
+     * @param message a short description of the outcome
+     */
     protected void passed(File file, String message) {
         passed(file + ": " + message);
     }
 
+    /**
+     * Concludes a check, reporting that the check succeeded.
+     *
+     * <p>This method should be called after previously calling {@code checking(...)}.
+     *
+     * @param message a short description of the outcome
+     */
     protected void passed(String message) {
         numTestsPassed++;
         print("Passed", message);
         out.println();
     }
 
+    /**
+     * Concludes a check for a file, reporting that the check failed.
+     *
+     * <p>This method should be called after previously calling {@code checking(...)}.
+     *
+     * @param file the file that was the focus of the check
+     * @param message a short description of the outcome
+     */
     protected void failed(File file, String message) {
         failed(file + ": " + message);
     }
 
+    /**
+     * Concludes a check for a file, reporting that the check failed.
+     *
+     * <p>This method should be called after previously calling {@code checking(...)}.
+     *
+     * @param message a short description of the outcome
+     */
     protected void failed(String message) {
         print("FAILED", message);
         StackWalker.getInstance().walk(s -> {
@@ -901,8 +941,6 @@
      * @param baseDir1 the directory in which to locate the first file
      * @param baseDir2 the directory in which to locate the second file
      * @param file the file to compare in the two base directories
-     * an error if the files do not match.
-     * @return true if the files are the same and false otherwise.
      */
     private void diff(File baseDir1, File baseDir2, String file) {
         String file1Contents = readFile(baseDir1, file);