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

[Andrew Haley]

On Thu, 17 Oct 2024 18:53:28 GMT, Jonathan Gibbons <jjg 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, separately from all the apis. It will apply to all the apis. 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.
> 
> Stylistically, the use of `=` for some options but not others is curious.

I'm finding all of this very hard to follow, mostly because I have no idea how apidiff is supposed to work. I'm just floundering about in the dark, really.

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

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