RFR: JDK-8274211: Test man page that options are documented

[Pavel Rappo]

On Wed, 6 Oct 2021 03:01:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a new test to compare the set of options documented in the javadoc man page against the set of options declared in the source.
> 
> Since there is currently a disparity, an "exception" mechanism is included so that the test can pass.   When the options have been added to the man page, this test is designed to fail, and the relevant strings should be removed from the `MISSING_IN_MAN_PAGE` list.
> 
> Test runs on all supported platforms.

Thank you for doing this, Jon.

test/langtools/jdk/javadoc/tool/CheckManPageOptions.java line 70:

> 68:             "--since",
> 69:             "--since-label",
> 70:             "--snippet-path");

Be specific, even if verbose:
Suggestion:

    List<String> MISSING_IN_MAN_PAGE = List.of(
            "--legal-notices",  // FIXME: JDK-8274295
            "--link-platform-properties",  // FIXME: JDK-8274295
            "--no-platform-links",  // FIXME: JDK-8274295
            "--since",  // FIXME: JDK-8274295
            "--since-label",  // FIXME: JDK-8274295
            "--snippet-path"); // FIXME: JDK-8266666

test/langtools/jdk/javadoc/tool/CheckManPageOptions.java line 95:

> 93:         toolDocletOnly.removeAll(MISSING_IN_MAN_PAGE);
> 94:         if (!toolDocletOnly.isEmpty()) {
> 95:             error(" The following options are defined by the tool or doclet, but not defined in the man page:\n"

Remove stray whitespace:
Suggestion:

            error("The following options are defined by the tool or doclet, but not defined in the man page:\n"

test/langtools/jdk/javadoc/tool/CheckManPageOptions.java line 156:

> 154:     }
> 155: 
> 156:     List<String> getToolOptions() throws Error {

I wonder if a better approach to get options would be to parse output of `javadoc -help`. After all, that is what we are after: ensure 1-1 correspondence between two documentation sources.

test/langtools/jdk/javadoc/tool/CheckManPageOptions.java line 287:

> 285:         return list;
> 286:     }
> 287:  }

Add trailing newline.

-------------

Marked as reviewed by prappo (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/5833