RFR: 7903866: apidiff: add an example to the doc [v3]

[Alan Bateman]

On Sun, 20 Oct 2024 11:43:04 GMT, Andrew Haley <aph at openjdk.org> wrote:

>> 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.
>
>> 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.
> 
> I find it very hard to understand the ifs and buts in the description of this option, and @alanbateman used the option this way. Please advise me to leave it in or take it out.

I used it in the example I gave Andrew to be explicit, no other reason. In any case, I agree we need some recipes in the docs. If they include a path to a build then probably better to use a path to a release build as someone is unlikely to be using fast debug build for this kinda of thing.

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

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