RFR: 7903866: apidiff: add an example to the doc

[Jonathan Gibbons]

On Wed, 16 Oct 2024 13:48:51 GMT, Andrew Haley <aph at openjdk.org> wrote:

> It's an example, for example. We need more.

src/share/doc/apidiff.md line 509:

> 507:     --jdk-build=/local/baseline-jdk/build/linux-x86_64-server-fastdebug --jdk-docs docs \
> 508:     --api sv \
> 509:     --jdk-build=/local/updated-jdk/build/linux-x86_64-server-fastdebug --jdk-docs docs \

`--jdk-docs` is not an api-specific option, and need only be given once, after all the apis have been specified. And, it is only necessary if there are multiple `*docs*` directories in the `build/.../images` directory -- although it is not wrong to give it anyway, just in case.

Stylistically, I would put the first `--api` option on its own line, to better illustrate the similarity between the two different APIs, but that's a matter of personal style.

src/share/doc/apidiff.md line 511:

> 509:     --jdk-build=/local/updated-jdk/build/linux-x86_64-server-fastdebug --jdk-docs docs \
> 510:     -d out \
> 511:     --compare-api-descriptions true \

It is intended that `--compare-api-descriptions` should default to `true`, although it is not wrong to be explicit.  If you found it to be necessary, that would be worth investigating.

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/26#discussion_r1805271951
PR Review Comment: https://git.openjdk.org/apidiff/pull/26#discussion_r1805274580