RFR: 8322036: Improve help output from the javadoc tool

[Pavel Rappo]

On Fri, 16 Aug 2024 15:03:58 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Could I please get a review for this small clenup? I updated the `--help` command output to match that of `man javadoc`.
> 
> I also noticed that  `--help-extended` was renamed to `--help-extra` at some point but doc-comment was not changed, so I changed it.
> I could create a separate issue for it if needed, just to keep a record of it.
> 
> The new `javadoc --help` output is the following 
> 
> 
> javadoc --help
> Usage:
>     javadoc [options] [packagenames] [sourcefiles] [@files]
> where options include:
>     @<file>       Read options and filenames from file
>     --add-modules <module>(,<module>)*
>                   Root modules to resolve in addition to the initial modules,
>                   or all modules on the module path if <module> is
>                   ALL-MODULE-PATH.
>     -bootclasspath <path>
>                   Override location of platform class files used for non-modular
>                   releases
>     -breakiterator
>                   Compute first sentence with BreakIterator
>     --class-path <path>, -classpath <path>, -cp <path>
>                   Specify where to find user class files
>     -doclet <class>
>                   Generate output via alternate doclet
>     -docletpath <path>
>                   Specify where to find doclet class files
>     --enable-preview
>                   Enable preview language features. To be used in conjunction with
>                   either -source or --release.
>     -encoding <name>
>                   Source file encoding name
>     -exclude <pkglist>
>                   Specify a list of packages to exclude
>     --expand-requires (transitive|all)
>                   Instructs the tool to expand the set of modules to be
>                   documented. By default, only the modules given explicitly on
>                   the command line will be documented. A value of "transitive"
>                   will additionally include all "requires transitive"
>                   dependencies of those modules. A value of "all" will include
>                   all dependencies of those modules.
>     -extdirs <dirlist>
>                   Override location of installed extensions
>     --help, -help, -?, -h
>                   Display command-line options and exit
>     --help-extra, -X
>                   Print a synopsis of nonstandard options and exit
>     -J<flag>      Pass <flag> directly to the runtime system
>     --limit-modules <module>(,<module>)*
>                   Limit the universe of observable modules
>     -locale <name>
>                   Locale to be used, e.g. en_US or en...

Nizar, thanks for doing this.

> this small clenup

It's not a cleanup, it's updating help output. It's important to be price here. Cleanup is optional, updating incorrect/inaccurate help output is not.

> I also noticed that `--help-extended` was renamed to `--help-extra` at some point but doc-comment was not changed, so I changed it.

Good catch! That said, I don't think there has ever been the `--help-extended` option or alias. It seems that `--help-extra` has been the correct alias for `-X` option for tools such as java, javac, javadoc, and jshell for as long as I can see. It's just javadoc inexplicably renamed it to `--help-extended` in [8237803][]. Later, `--help-extended` also appeared in [8294546][].

My guess, is that it's how @jonathan-gibbons (mis)remembered `-X`'s alias in his head. To Jon's credit, the relevant `OptionKind.EXTENDED` enum name is confusing. But since the above PRs were reviewed by me and @jddarcy respectively, if there's anyone to blame, it's us.

If my guess is correct, those two occurrences of `--help-extended` should be deleted. One is deleted in this PR, another should be deleted by compiler people. I'll haven't yet finished looking at this PR. If I have more comments, I'll post them later. Thanks.

[8237803]: https://mail.openjdk.org/pipermail/javadoc-dev/2020-January/001324.html	"(sorry, pre git)"
[8294546]: https://github.com/openjdk/jdk/pull/10566

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

PR Comment: https://git.openjdk.org/jdk/pull/20618#issuecomment-2296275585