7903802: apidiff: minor doc and related updates

Reviewed-by: iris

Author: jonathan-gibbons

src/share/doc/README

@@ -3,11 +3,10 @@ API Comparison Utility: apidiff
 
 Introduction
 
-...
-
-Release Notes.
-
-...
+APIDiff is a utility to compare two or more versions of an API, each as
+defined by a series of options similar to those supported by `javac`.
+For details on all the options, see the file 'doc/apidiff.html' in this
+distribution.
 
 
 System Requirements
@@ -17,7 +16,7 @@ apidiff.
 
 - Java platform
     A platform equivalent to JDK 17 or later is required.
-
+    It should be at least as recent as that for each of the APIs to be compared.
 
 
 Files and Directories
@@ -27,8 +26,8 @@ README          This file
 COPYRIGHT       Copyright information
 LICENSE         License file
 doc/            Documentation files
-legal/          Copyright and license files
+legal/          Additional copyright and license files
 lib/            Directory containing the JAR files needed to run apidiff
-bin/            Miscellaneous utility script for use on Linux, macOS, Solaris
+bin/            Miscellaneous utility script for use on Linux, macOS,
                 and for Cygwin on Microsoft Windows platforms
 

src/share/doc/apidiff.md

@@ -1,6 +1,6 @@
 ---
 #
-# Copyright (c) 2019, 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2019, 2024, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -22,20 +22,17 @@
 # questions.
 #
 
-title: 'APIDIFF(1) 0.1 | CodeTools'
-date: 2021
+title: 'APIDIFF(1) 1.0 | CodeTools'
+date: 2024
 lang: en
 ---
 
-<b style="color:red">WORK IN PROGRESS</b>
-
 ## Name
 
 apidiff - compare different versions of an API
 
 ## Synopsis
 
-
 `apidiff` \[*options*\]
 
 *options*
@@ -44,7 +41,7 @@ apidiff - compare different versions of an API
 ## Description
 
 The `apidiff` command reads source, class and HTML files that provide different versions
-of an API, compares corresponding files in the different versions and writes out
+of an API, compares corresponding declarations in the different versions and writes out
 an HTML report.  The comparison includes:
 
 * structural changes, such as whether an element was added, changed or removed,
@@ -339,7 +336,7 @@ of the API to be compared.
 If the API does not provide or is not part of a module, use the `--source-path`
 and `--class-path` options.
 If the API provides or is part of one or more modules, use the
-`--source-path`, `--module-source-path`, `--module-path` and related options.
+`--source-path`, `--module-source-path`, `--module-path`, and related options.
 
 If you want to compare the content of documentation comments, you must provide
 source files for all the elements to be compared; any dependencies of those source
@@ -348,7 +345,9 @@ files can be specified as either source or class files.
 If you want to compare the API descriptions, you must provide the locations
 of the directories generated by the `javadoc` tool for each of the instances
 of the API being compared. This is often a directory whose path ends in `api`,
-although that is not a requirement.
+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.
 
 ### Configuring instances of JDK to be compared