RFR: 8322036: Improve help output from the javadoc tool [v2]
Nizar Benalla
nbenalla at openjdk.org
Thu Aug 22 18:11:17 UTC 2024
On Thu, 22 Aug 2024 13:17:24 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 u...
>
> 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 two additional commits since the last revision:
>
> - Merge remote-tracking branch 'upstream/master' into javadoc-help
> - improve javadoc help output
>
> small clenup, --help-extended was renamed to --help-extra at some point but doc-comment was not changed
These new changes address the review comments. I replaced backticks with single quotes and dropped the unnecessary use of underscores.
I capitalized the first letter of "doclet" in `Provided by the Standard doclet:` , as "Standard" is also capitalized [here](https://github.com/openjdk/jdk/blob/6041c936d6dd39c5b3a89ed2823b25a8aef42b9f/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java#L91).
Do you we want to capitalize or lowercase this?
The new 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_US_WIN
--module <module>(,<module>)*
Document the specified module(s)
--module-path <path>, -p <path>
Specify where to find application modules
--module-source-path <path>
Specify where to find input source files for multiple modules
-package
Show package/protected/public types and members. For
named modules, show all packages and all module details.
-private
Show all types and members. For named modules,
show all packages and all module details.
-protected
Show protected/public types and members (default). For
named modules, show exported packages and the module's API.
-public
Show only public types and members. For named modules,
show exported packages and the module's API.
-quiet Do not display status messages
--release <release>
Provide source compatibility with specified release
--show-members <value>
Specifies which members (fields, methods, or constructors) will be
documented, where value can be one of "public", "protected",
"package" or "private". The default is "protected", which will
show public and protected members, "public" will show only
public members, "package" will show public, protected and
package members and "private" will show all members.
--show-module-contents <value>
Specifies the documentation granularity of module
declarations. Possible values are "api" or "all".
--show-packages <value>
Specifies which module packages will be documented. Possible
values are "exported" or "all" packages.
--show-types <value>
Specifies which types (classes, interfaces, etc.) will be
documented, where value can be one of "public", "protected",
"package" or "private". The default is "protected", which will
show public and protected types, "public" will show only
public types, "package" will show public, protected and
package types and "private" will show all types.
--source <release>, -source <release>
Provide source compatibility with specified release
--source-path <path>, -sourcepath <path>
Specify where to find source files
-subpackages <subpkglist>
Specify subpackages to recursively load
--system <jdk>
Override location of system modules used for modular releases
--upgrade-module-path <path>
Override location of upgradeable modules
-verbose Output messages about what Javadoc is doing
--version Print version information
-Werror Report an error if any warnings occur
Provided by the Standard Doclet:
--add-script <file>
Add a script file to the generated documentation
--add-stylesheet <file>
Add a stylesheet file to the generated documentation
--allow-script-in-comments
Allow JavaScript in documentation comments, and options
whose value is html-code
-author Include @author paragraphs
-bottom <html-code>
Include bottom text for each page
-charset <charset>
Charset for cross-platform viewing of generated documentation
-d <directory>
Destination directory for output files
-docencoding <name>
Specify the character encoding for the output
-docfilessubdirs
Enables deep copying of 'doc-files' directories. Subdirectories and all
contents are recursively copied to the destination
-doctitle <html-code>
Include title for the overview page
-excludedocfilessubdir <name>,<name>,...
Exclude any 'doc-files' subdirectories with given name.
':' can also be used anywhere in the argument as a separator.
-footer <html-code>
This option is no longer supported and reports a warning
-group <name> <g1>,<g2>...
Group specified elements together in overview page.
':' can also be used anywhere in the argument as a separator.
-header <html-code>
Include header text for each page
-helpfile <file>
Specifies a file containing the text that will be displayed when the
help link in the navigation bar is clicked
-html5 Generate HTML 5 output. This option is no longer required.
--javafx, -javafx
Enable JavaFX functionality
-keywords Include HTML meta tags with package, class and member info
-link <url> Create links to javadoc output at <url>
--link-modularity-mismatch (warn|info)
Report external documentation with wrong modularity with either
a warning or informational message. The default behaviour is to
report a warning.
-linkoffline <url1> <url2>
Link to docs at <url1> using package list at <url2>
--link-platform-properties <url>
Link to platform documentation URLs declared in properties file at <url>
-linksource Generate source in HTML
--main-stylesheet <file>, -stylesheetfile <file>
File to change style of the generated documentation
-nocomment Suppress description and tags, generate only declarations
-nodeprecated
Do not include @deprecated information
-nodeprecatedlist
Do not generate deprecated list
--no-fonts Do not include standard web fonts in generated documentation
-nohelp Do not generate help link
-noindex Do not generate index
-nonavbar Do not generate navigation bar
--no-platform-links
Do not generate links to the platform documentation
-noqualifier <name1>,<name2>,...
Exclude the list of qualifiers from the output.
':' can also be used anywhere in the argument as a separator.
-nosince Do not include @since information
-notimestamp Do not include hidden time stamp
-notree Do not generate class hierarchy
--override-methods (detail|summary)
Document overridden methods in the detail or summary sections.
The default is 'detail'.
-overview <file>
Read overview documentation from HTML file
-serialwarn Reports compile-time warnings for missing '@serial' tags
--since <release>(,<release>)*
Document new and deprecated API in the specified releases
--since-label <text>
Provide text to use in the heading of the "New API" page
--snippet-path <path>
The path for external snippets
-sourcetab <tab length>
Specify the number of spaces each tab takes up in the source
--spec-base-url
Specify a base URL for relative URLs in @spec tags
-splitindex Split index into one file per letter
-tag <name>:<locations>:<header>
Specifies a custom tag with a single argument
-taglet The fully qualified name of Taglet to register
-tagletpath The path to Taglets
-top <html-code>
Include top text for each page
-use Create class and package usage pages
-version Include @version paragraphs
-windowtitle <text>
Browser window title for the documentation
GNU-style options may use = instead of whitespace to separate the name of an
option from its value.
-------------
PR Comment: https://git.openjdk.org/jdk/pull/20618#issuecomment-2305348598
More information about the javadoc-dev
mailing list