7903859: add more details to the top-level README.md file

Reviewed-by: iris

Author: jonathan-gibbons

README.md

@@ -8,21 +8,33 @@ defined by a series of options similar to those supported by `javac`.
 `apidiff` uses the following dependencies:
 
 * _[Daisy Diff]_: an HTML comparison library, required when building `apidiff`
+* _[Equinox]_: the Eclipse Common Runtime, used by Daisy Diff; it is required
+  when building Daisy Diff from source, but may already be included if using
+  a precompiled copy of Daisy Diff in a JAR file.
+* _[HTMLCleaner]_ : a library to sanitize HTML prior to comparison with Daisy Diff
 * _[Java Diff Utils]_: a plain-text comparison library, required when building `apidiff`
 * _[JUnit]_: the testing framework, used to run some of the tests for `apidiff`
 
 Suitable versions of these dependencies can be downloaded by running
-`make/build.sh`.
+`make/build.sh`, using configuration details in `make/build-support/version-numbers`.
 
 ### Building with GNU Make
 
-The default configuration uses values provided in `make/dependencies.gmk`,
-unless these values have been overridden on the command line used to run `make`.
+If you have run `make/build.sh`, there will be a convenient shell script stored
+in `build/make.sh` that runs `make` with variables set to the locations of the
+downloaded dependencies. You may also run `make` directly, using _make_ variables
+to specify the locations of any necessary dependencies.
 
 ````
-    make -C make Makefile <target>
+    sh build/make.sh <target>
 ````
 
+Useful targets are:
+
+* `sanity` -- to check settings of necessary _make_ variables,
+* `build` -- to build the files for a release, and
+* `test` -- to run all the available tests.
+
 ### Building with an IDE
 
 An IDE such as IntelliJ IDEA needs the following configuration:
@@ -33,6 +45,13 @@ An IDE such as IntelliJ IDEA needs the following configuration:
   * _Daisy Diff_, _HTMLCleaner_, _Java Diff Utils_ available for compilation
   * _JUnit_ available for testing
 
+_Note:_ when working in an IDE, it is strongly recommended that you use
+a precompiled JAR file for Daisy Diff. The source files refer to additional
+dependencies that are not required or downloaded for APIDiff. While these
+source files are ignored when building APIDiff with GNU Make, it may not
+be possible to exclude those source files when registering Daisy Diff as
+a source-file dependency in the IDE.
+
 In addition, some JUnit tests require access to internal classes in
 the `jdk.compiler` and `jdk.jdeps` modules:
 
@@ -51,22 +70,51 @@ The following compiler options may also be desirable:
 ````
 
 _Note:_ When working on the test files, be careful not to mark module source directories
-as `Test Sources Root` at the same time as any source directories that are not 
+as `Test Sources Root` at the same time as any source directories that are not
 for a module.
 
+## Testing `apidiff`
+
+You can run the tests using the `test` target for GNU Make, using either
+`make/build.sh` or the subsequently generated `build/make.sh`. You can
+specify either the overall `test` target or the absolute path name of
+the `*.ok` file for any individual tests. That being said, most of the
+tests are written as JUnit tests, and can either be invoked as a group
+as part of the overall `test` target, or individually, by using JUnit
+directly, either using the JUnit command-line tool, or by using JUnit
+support within an IDE.
+
+Just as some `--add-exports` options are needed to compile APIDiff,
+the same options will need to be provided in any IDE configuration used
+to run tests.
+
 ## Documentation
 
 A "man" page is generated as part of the build, and is the primary source
-of information for how to run `apidiff`.
+of information for how to run `apidiff`. The tool also provides simple
+command-line help, listing the available options and a summary of their
+meaning.
+
+You can see recent versions of the documentation on the APIDiff
+[project page][apidiff-project]:
+
+* ["man" page][apidiff-man]
+* [command-line help][apidiff-cmdline-help]
+
+[apidiff-project]: https://openjdk.org/projects/code-tools/apidiff/
+[apidiff-man]: https://openjdk.org/projects/code-tools/apidiff/apidiff.html
+[apidiff-cmdline-help]: https://openjdk.org/projects/code-tools/apidiff/cmdline-help.html
 
 ## ShowDocs
 
-`showDocs` is a small utility program that is a simple wrapper around the 
+`showDocs` is a small utility program that is a simple wrapper around the
 `APIReader` and `SerializedFormReader` classes in `apidiff`, that can provide
 filtered views of the files generated by `javadoc`, in order to view the
 parts of those files that will be compared by `apidiff`.
 
 
 [Daisy Diff]: https://github.com/DaisyDiff/DaisyDiff
+[Equinox]: https://projects.eclipse.org/projects/eclipse.equinox
+[HtmlCleaner]: https://htmlcleaner.sourceforge.net
 [Java Diff Utils]: https://github.com/java-diff-utils/java-diff-utils
 [JUnit]: https://junit.org/

src/share/doc/apidiff.md

@@ -349,6 +349,13 @@ although that is not a requirement. To eliminate any false positive differences
 being introduced by changes to the `javadoc` tool itself, the same or equivalent
 versions of `javadoc` should be used for each API to be compared.
 
+If you want to compare all the exported packages in a module, use
+`--include <module>/**`.  If you want to compare the contents of
+specific packages in a module, use `--include <module>/<package>.*`
+or `--include <module>/<package>.**`. The `.**` form will also include
+the contents of any subpackages.  You can use multiple `--include`
+options to include different parts of an API in the comparison.
+
 ### Configuring instances of JDK to be compared
 
 `apidiff` can be used to compare different instances of JDK, but that can be
@@ -420,6 +427,15 @@ you can combine the recommended options for the two modes, specifying both
 `--patch-module` options for the source files and `--api-directory` for the
 generated documentation.
 
+If you are using the `--jdk-build` option, and the corresponding `images`
+directory has multiple matches for `images/*docs*`, you will need to use
+the `--jdk-docs` option to disambiguate which documentation directory to use.
+The value that you give should be the name of one of those subdirectories
+of the `images` directory. The `--jdk-docs` option is not specific to any
+individual API, and need only be given once on the command-line.
+It will be used as needed to disambiguate the documentation directory to be
+used for any API that is defined by using the `--jdk-build` option.
+
 If you want to see or understand how the options are used internally, you
 can use `--verbose options`, possibly implicitly as part of `--verbose all`.