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

[jonathan-gibbons]

Please review an update to the main documentation page for the apidiff tool. The updates are primarily clarifications and examples, intended to reduce some of the recent confusion about using the tool. As well as clarification and examples throughout the page, two more full examples are given at the end. These examples have been tested with scripts. They are meant to be indicative of what one might use to create a diff report for a CSR submission.

The generated HTML for the page can be seen here: https://cr.openjdk.org/~jjg/7903876/doc/apidiff.html

For the record, the scripts used to test the examples are as follows:

*** play/apidiff-examples/apidiff-1.sh
#!/bin/bash

JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff

PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
apidiff \
    --api jdk24 --jdk-build build/baseline \
    --api 8330183 --jdk-build build/macosx-aarch64-server-release  \
    --include java.compiler/** \
    --output-directory build/apidiff

*** play/apidiff-examples/apidiff-2.sh
#!/bin/bash

JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff

PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
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)"

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issue

• CODETOOLS-7903876: Improve the man page, with (more) examples (Enhancement - P3)

Reviewers

• Iris Clark (@irisclark - Reviewer) ⚠️ Review applies to 22ccba28

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/apidiff.git pull/28/head:pull/28
$ git checkout pull/28

Update a local copy of the PR:
$ git checkout pull/28
$ git pull https://git.openjdk.org/apidiff.git pull/28/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 28

View PR using the GUI difftool:
$ git pr show -t 28

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/apidiff/pull/28.diff

Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back jjg! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@jonathan-gibbons This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

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

Reviewed-by: iris

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been no new commits pushed to the master branch. If another commit should be pushed before you perform the /integrate command, your PR will be automatically rebased. If you prefer to avoid any potential automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[mlbridge]

Webrevs

• 01: Full - Incremental (3d316243)
• 00: Full (22ccba28)

[irisclark]

Great man page expansion! I like the additional examples (particularly the one for CSRs). I'm sure there are several other common cases which could use examples.

[jonathan-gibbons]

/integrate

[openjdk]

Going to push as commit 1dbbcb5.

[openjdk]

@jonathan-gibbons Pushed as commit 1dbbcb5.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.