RFR: 8350007: Add usage message to the javadoc executable [v3]

[Nizar Benalla]

On Wed, 26 Feb 2025 18:36:50 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 560:
>> 
>>> 558:                     showLinesUsingKey("main.usage.short");
>>> 559:                     showLinesUsingKey("main.for-more-details-see-usage");
>>> 560:                     return OK;
>> 
>> The currently used exit code is `2`, and the message is written to `stderr`, not `stdout`. I think these things should not be changed.
>
> `jpackage` and `jar` return 0 if there are no args. `javap` returns `2`/`EXIT_CMDERR` so it's not very consistent.
> 
> This is the behavior when returning `CMDERR`
> 
> 
> nizar-mac! $ javadoc 
> error: an unknown error has occurred
> Usage:
>     javadoc [options] [packagenames] [sourcefiles] [@files]
> For more details on available options, use --help or --help-extra
> 1 error
> 
> 
> I'm not sure we want to emit an error? Returning 0 or 1 might better.
> But I can understand why we would want to keep those things the same.

For the record, I discussed this offline with a couple of people.
Since the user didn't ask for the help message, this is indeed be an invalid run and returning a non-zero value might  be the right thing to do.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23618#discussion_r1972341508