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

[Jonathan Gibbons]

On Wed, 6 Oct 2021 10:38:47 GMT, Pavel Rappo <prappo 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.
>
> 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

Yeah, but ... I'd prefer to put effort into resolving these right away.  I view the `MISSING_IN_MAN_PAGE` support as a very short-term workaround so that we can integrate the test while we fix the man page sources.  (It went in as a last-minute feature, as an alternate solution to marking the current issue (for a new test) as "Blocked By" the issues for the missing options.

> 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.

I did wonder whether to include a check for command-line help, but generally, by construction, the command-line help output is derived from the various internal option objects, so I'm not sure it adds much.

And, I'm not sure I agree that we are primarily out to sure that 1-1 correspondence between the doc sources ... that would not detect an option that was erroneously missing from both doc sources.   IMO, we are primarily out to ensure that the docs match the implementation, not any other docs.

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

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