7903876: Improve the man page, with (more) examples

Reviewed-by: iris

Author: jonathan-gibbons

src/share/classes/jdk/codetools/apidiff/Main.java

@@ -176,7 +176,7 @@ private Result run(List<String> args, Log log) {
         }
 
         // TODO: when APIDiff moves to JDK 21, thia can trivially become SequencedSet,
-        //       which would be useful in varoius places, such as PageReporter.getResultGlyph
+        //       which would be useful in various places, such as PageReporter.getResultGlyph
         Set<API> apis = options.allAPIOptions.values().stream()
                 .map(a -> API.of(a, s, ak, log, verboseOptions))
                 .collect(Collectors.toCollection(LinkedHashSet::new));

src/share/classes/jdk/codetools/apidiff/Options.java

@@ -97,7 +97,7 @@ public static class APIOptions {
         public String source;
 
         /**
-         * Whether or not {@code --enable-preview} has been specified.
+         * Whether {@code --enable-preview} has been specified.
          */
         public boolean enablePreview;
 

src/share/doc/apidiff.md

@@ -53,24 +53,49 @@ an HTML report.  The comparison includes:
 
 ## Options
 
-`apidiff` provides different groups of options, to specify
-the [APIs](#the-apis) and
-the [elements in those APIs](#the-elements-to-be-compared) to be compared,
-[output options](#output-options) for the report to be generated, and
-[other options](#other-options).
+`apidiff` provides different groups of options, to specify:
+
+* the [APIs](#the-apis) to be compared,
+* the [elements](#the-elements-to-be-compared) (declarations) in those APIs to be compared,
+* the [output options](#output-options) for the report to be generated, and
+* [other options](#other-options).
+
+All options have a long form, beginning with `--`. Some options may have
+a single-letter form, beginning with just `-`. For those options that take
+an argument, the value may be separated from the option name by either white
+space or '='. In general, as is common with most JDK tools, if an option
+is repeated, the rule is "last one wins". This rule is modified for
+the options that specify the APIs to be compared, such that "last one wins"
+only applies within the group of API-specific options used to define each API.
+
+To see detailed information about how the options are processed, 
+use [`--verbose options`](#option-verbose).
 
 ### The APIs
 
 To specify each of the APIs to be compared, use the `--api` _name_ option
-followed by a series of options that apply to that API. Most of the options are the
-same as the corresponding _javac_ option; see the _javac_ documentation for more details
-about those options.
+followed by a series of _API-specific options_ that apply to that API. 
+
+The API-specific options must at least include options to find the source
+or class files for the declarations to be compared. The options should 
+also define the location of the generated documentation if that is to be
+included in the comparison. (When comparing the API documentation, it is
+not enough to just specify the location of that documentation.)
+
+Note that the API-specific options for each API are separate and distinct
+from the API-specific options for any other API. 
 
 <a id="option-api">`--api` _name_</a>
 :   Specifies a name for the API and sets the [current API](#the-current-api) for
     use by the API-specific options that immediately follow this option.
-    The option, and the API-specific options that follow, should be provided for each API
-    to be compared.
+    The name will appear in the generated reports when identifying any differences.
+    If the generated report will be publicly shared, it is recommended that
+    the name should be reasonably meaningful to any readers.
+    A longer, more descriptive label may also be given with the `--label` option.
+
+    The option, and the API-specific options that follow, should be provided for 
+    each API to be compared.
+
     The order in which the `--api` options first appear on the command line determines
     the order in which any differences are reported.  It is recommended to specify the
     options in chronological order, from the oldest version of the API to the most recent
@@ -81,20 +106,48 @@ about those options.
     If given, it should be the top-level directory of the documentation generated by
     the `javadoc` command for the API.
 
-<a id="option-class-path">`--class-path` *path*, `-classpath` *path*, or `-cp` *path*</a>
-:   Specifies where to find files for the class path for the [current API](#the-current-api).
-
-<a id="option-enable-preview">`--enable-preview`</a>
-:   Enables preview language features for the [current API](#the-current-api).
-
 <a id="option-jdk-build">`--jdk-build` *directory*</a>
 :   Specifies a directory containing a JDK build from which to infer values for
-    various options. For example, *repository*`/build/`*configuration-name*
+    various options. The builds can either be for default-named configurations in
+    separate repositories or work areas, or for differently named configurations in
+    the same repository. (To create different configurations within the same JDK
+    repository, use the `--with-conf-name` option when running `sh ./configure`
+    to create the configuration.)
+
+    It is a matter of personal preference whether to use separate repositories
+    or separate configurations within a single repository for the instances
+    of the API to be compared.
+    
+    * Using separate repositories uses more disk space, but makes it more
+      convenient to not have to specify the desired configuration every time 
+      you run `make`.
+    * Using separate configurations in a single repository uses less disk space,
+      but means that you will have to indicate which configuration to use
+      every time you run `make`.
+
+    When using this option, it should not be necessary to give any additional 
+    `javac`-like options, like `--module-path` or `--release`.
+    
+    For example, 
+
+    * `--jdk-build` *repository*`/build/`*configuration-name*
+    * `--jdk-build /Users/Duke/jdk-dev/build/macosx-aarch64`
+    * `--jdk-build /Users/Duke/jdk-dev/build/macosx-aarch64-server-release`
+    * `--jdk-build $HOME/OpenJDK/build/linux-x86_64-server-fastdebug`
 
 <a id="option-label">`--label` *text*</a>
 :   Specifies a short plain-text label for the API, to be included in the generated
     reports. For example, the full version string for the instance of the API being compared.
 
+The following API options are similar to the corresponding `javac` option; 
+see the `javac` documentation for more details about the arguments for those options.
+
+<a id="option-class-path">`--class-path` *path*, `-classpath` *path*, or `-cp` *path*</a>
+:   Specifies where to find files for the class path for the [current API](#the-current-api).
+
+<a id="option-enable-preview">`--enable-preview`</a>
+:   Enables preview language features for the [current API](#the-current-api).
+
 <a id="option-module-path">`--module-path`</a> *path* or `-p` *path*</a>
 :   Specifies where to find application modules for the [current API](#the-current-api).
 
@@ -129,6 +182,13 @@ pairwise, with each of the older instances being compared against the newest ins
 
 ### The Elements to be Compared
 
+The following options are used to specify the elements (declarations) to be compared
+within the [APIs](#the-apis), specified by the various `--api` options and associated
+API-specific options.
+
+These options apply equally to all the APIs to be compared: there is no need
+to repeat these options for each API to be compared. 
+
 <a id="option-access">`--access` `public|protected|package|private`</a>
 :   Specifies the access of the declarations to be compared. The default is `protected`.
 
@@ -142,19 +202,20 @@ pairwise, with each of the older instances being compared against the newest ins
     methods and fields.
 
 <a id="option-exclude">`--exclude` *pattern*</a>
-:   Specifies the patterns for modules or packages to be excluded from the
-    comparison.
+:   Specifies the [patterns](#patterns) for modules or packages to be excluded 
+    from the comparison. The default is that none of the elements specified with
+    `--include` options are excluded.
 
 <a id="option-include">`--include` *pattern*</a>
-:   Specifies the patterns for modules or packages to be included from the
-    comparison.
+:   Specifies the [patterns](#patterns) for modules or packages to be included 
+    in the comparison. There must be at least one `--include` option.
 
 <a id="option-compare-api-descriptions">`--compare-api-descriptions` *boolean*</a>
-:   Specifies that the API descriptions (as generated by javadoc) should be compared
+:   Specifies that the API descriptions (as generated by `javadoc`) should be compared
     for each element being compared.
-    The option defaults to `true` if documentation comments are not to be compared
-    and if an API directory is given for each instance of the API to be
-    compared. (See `--compare-doc-comments`).
+    The option defaults to `true` if an API directory is given for each instance 
+    of the API to be compared and if documentation comments are not to be compared. 
+    (See `--compare-doc-comments`).
     When the option is enabled, either explicitly or by default,
     the API directory must be specified for each instance of the API
     to be compared, and set to the location of the files generated by `javadoc`
@@ -163,7 +224,7 @@ pairwise, with each of the older instances being compared against the newest ins
     option, or indirectly, with the `--jdk-build` and `--jdk-docs` options.
 
 <a id="option-compare-api-descriptions-as-text">`--compare-api-descriptions-as-text` *boolean*</a>
-:   Specifies that the HTML for the API descriptions (as generated by javadoc)
+:   Specifies that the HTML for the API descriptions (as generated by `javadoc`)
     should be compared as plain text for each element being compared. If the argument is `true`,
     this option also implies `--compare-api-descriptions true`.
 
@@ -178,6 +239,10 @@ pairwise, with each of the older instances being compared against the newest ins
 <a id="option-jdk-docs">`--jdk-docs` *name*</a>
 :   In conjunction with the `--jdk-build` option, specifies the name of the
     documentation bundle to use when more than one is available.
+    It need not be specified if all the APIs specified by `--jdk-build`
+    have exactly one directory matching the name `images/*docs*`:
+    this is typically the case when building the OpenJDK `docs` or `docs-jdk`
+    targets.
     For example, `docs`, `javase-docs`, `reference-docs`.
 
 ### Output Options
@@ -232,13 +297,22 @@ pairwise, with each of the older instances being compared against the newest ins
 
 <a id="option-verbose">`--verbose` _flag_[`,`_flag_]*</a>
 :   Specifies the kinds of verbose output. _flag_ may be one of
-    `all`, `none`, or one of the following, optionally preceded by `-`:
+    `all`, `none`, or one of the following, optionally preceded by `-` to negate the flag:
     `module`, `package`, `type`, `time`, `options`.
 
+    | Flag      | Description                                                                |
+    |:----------|:---------------------------------------------------------------------------|
+    | `module`  | Report on the modules being compared                                       |
+    | `package` | Report on the modules and packages being compared                          |
+    | `type`    | Report on the modules, packages, and classes and interfaces being compared |
+    | `time`    | Report the time taken to perform the comparison and generate the reports   |
+    | `options` | Report how the command-line options are processed                          |
+
 <a id="option-at">`@`*filename*</a>
 :   Reads options from a file. To shorten or simplify the `apidiff` command, you can specify
     one or more files that contain arguments for the `apidiff` command. This lets you create
-    `apidiff` commands of any length on any operating system.
+    `apidiff` commands of any length on any operating system. The syntax for the contents
+    of the file is similar to that for other JDK commands, like `javac` and `javadoc`.
 
 ## Exit Status
 
@@ -256,7 +330,7 @@ The `--help` and `--version` options exit with a status of 0.
 ## The Current API
 
 The current API is the API specified by the most recent `--api` option on the command line,
-and is the API for which any API-specific options will apply.
+and is the API for which any subsequent API-specific options will apply.
 
 The "current API" is cancelled when any option is given that is not specific to
 any one API. Additional options for an API can be given by repeating the `--api`
@@ -299,6 +373,16 @@ module part.
 in the unnamed module, and so either all patterns must include a module part,
 or none must.
 
+For example,
+
+  * `java.base/java.nio.**` matches all types in the `java.nio` packages
+    and corresponding subpackages, in the `java.base` module
+  * `java.compiler/**` matches all packages and types in the `java.compiler`
+    module
+
+Depending on how you invoke `apidiff`, you may need to quote the pattern
+to prevent the `*` characters being interpreted by a command shell.
+
 ## Notes
 
 A "notes" file is used to specify links to be injected into the generated report
@@ -395,11 +479,15 @@ as generated by the standard JDK makefiles.
 
   In conjunction with this option, use the `jdk-docs` option to specify the name
   of the docs bundle to be compared, when there is more than one. Note this option
-  applies to all instances to be compared, and is not specific to the
-  [current API](#the-current-api). Use the `--compare-doc-comments` and
-  `--compare-api-descriptions` as needed to indicate the comparisons to be included
-  in the report.  If neither are specified, `--compare-api-descriptions` is
-  the default.
+  applies to all instances to be compared, and need only be given once; 
+  it is not specific to the [current API](#the-current-api). 
+  Use the `--compare-doc-comments` and `--compare-api-descriptions` as needed 
+  to indicate the comparisons to be included in the report.  
+  If neither are specified, `--compare-api-descriptions` is the default.
+
+While the `--jdk-build` option provides a convenient way to have the tool
+automatically generate the equivalent underlying options, you can instead
+specify those options directly.
 
 * If you just want to compare some or all of the declarations in different
   instances of JDK, without comparing the documentation comments or API documentation,
@@ -456,7 +544,7 @@ can use `--verbose options`, possibly implicitly as part of `--verbose all`.
 When comparing any generated API documentation, the comparison is sensitive to any
 variations caused by the version of `javadoc` used to generate the documentation.
 Therefore, it is highly recommended to use the same version of `javadoc` to generate
-all the versions of the documentation to be compared.  When building JDK, although
+the documentation for all the versions to be compared.  When building JDK, although
 the standard `docs` and `docs-jdk` targets will use the version of `javadoc` in the
 same repository, you can specify the version of JDK to be used for targets like
 `docs-reference-api` with the `--with-docs-reference-jdk` option to `configure`,
@@ -470,6 +558,46 @@ CSR request, when there is no change in `javadoc` in the versions being compared
 it is reasonable to use the standard `docs` or `docs-jdk` targets to generate the API
 documentation to be compared.
 
+### Comparing non-JDK APIs
+
+If the API does not define any modules, use an appropriate combination of the
+`--source-path`, `--class-path`, and `--api-directory` options.
+You can put either the compiled classes or a JAR file on the class path.
+If you want to compare documentation comments, put the source files on the 
+source path. If you want to compare the API documentation, use the 
+`--api-directory` to specify the root directory of the documentation.
+
+For example, to set up an API to be able to compare the API documentation 
+associated with a JAR file:
+
+    --api before --class-path build/example.jar --api-directory build/docs/api
+
+To set up an API to be able to compare the documentation comments for a project:
+
+    --api before --source-path src/main/java
+
+In both cases, you can specify any additional dependencies on the class path.
+
+If the API defines one or more modules, use an appropriate combination of the
+`--module-source-path`, `--module-path`, and `--api-directory` options.
+You can put either the module or a directory of modules on the module path,
+where a module is anything that can be recognized as such by `javac`.
+If you want to compare documentation comments, put the source files on the
+module source path. If you want to compare the API documentation, use the
+`--api-directory` to specify the root directory of the documentation.
+
+For example, to set up an API to be able to compare the API documentation 
+associated with the modules for a project:
+
+    --api before --module-path build/modules --api-directory build/docs/api
+
+To set up an API to be able to compare the documentation comments for a 
+project that defines a module called `com.example`:
+
+    --api before --module-source-path com.example=src/main/java
+
+In both cases, you can specify any additional dependencies on the module path. 
+
 ### Comparing documentation comments or API descriptions
 
 As well as comparing the declarations found in source files or compiled class files,
@@ -510,9 +638,11 @@ The tool does _not_ attempt to run `javadoc` locally to generate the page on the
 [Java Language Model API]: https://docs.oracle.com/en/java/javase/17/docs/api/java.compiler/javax/lang/model/package-summary.html
 [Compiler Tree API]: https://docs.oracle.com/en/java/javase/17/docs/api/jdk.compiler/com/sun/source/doctree/package-summary.html
 
-## Example
+## Examples
 
-To compare APIs in the `java.base` module in JDK builds `/local/baseline-jdk` and `/local/updated-jdk`, and place the result in the directory `out`, run the following command:
+To compare APIs in the `java.base` module in JDK builds `/local/baseline-jdk` 
+and `/local/updated-jdk`, and place the result in the directory `out`, 
+run the following command:
 
 ```
 bin/apidiff \
@@ -526,3 +656,30 @@ bin/apidiff \
     --include 'java.base/**'
 ```
 
+To compare the changes for the fix for an issue such as JDK-8330183, 
+using two separate configurations in the same repo, use a command like this:
+
+```
+apidiff \
+    --api jdk24 --jdk-build build/baseline \
+    --api 8330183 --jdk-build build/macosx-aarch64-server-release  \
+    --include 'java.compiler/**' \
+    --output-directory build/apidiff
+```
+
+While the previous example is minimal, it could be augmented by
+providing additional details to be included in the output, and
+additional options to be explicit about some of the desired settings.
+
+```
+apidiff \
+    --api jdk24 --jdk-build build/baseline --label "The baseline for the changes"\
+    --api 8330183 --jdk-build build/macosx-aarch64-server-release --label "Add SourceVersion.RELEASE_24" \
+    --include 'java.compiler/**' \
+    --output-directory build/apidiff \
+    --compare-api-descriptions true \
+    --jdk-docs docs \
+    --info-text top="This proposal is not yet final" \
+    --title "Diffs for JDK-8330183 CSR" \
+    --description "Generated by $USER at $(date -u)"
+```