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

[Nizar Benalla]

On Wed, 26 Feb 2025 17:32:37 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Nizar Benalla has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains four additional commits since the last revision:
>> 
>>  - respond to feedback
>>  - Merge branch 'master' into javadoc-usage-message
>>  - update test with new usage message
>>  - improve javadoc executable message
>
> 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.

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

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