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

[Iris Clark]

On Thu, 24 Oct 2024 23:52:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> 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)"

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.

-------------

Marked as reviewed by iris (Reviewer).

PR Review: https://git.openjdk.org/apidiff/pull/28#pullrequestreview-2397602583