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

[Jonathan Gibbons]

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

This pull request has now been integrated.

Changeset: 1dbbcb5b
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/1dbbcb5b87f75edcbdf9caf7314c56bce1a110df
Stats:     202 lines in 3 files changed: 163 ins; 6 del; 33 mod

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

Reviewed-by: iris

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

PR: https://git.openjdk.org/apidiff/pull/28