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

[Jonathan Gibbons]

On Sun, 20 Oct 2024 15:40:47 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>>> 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.

@AlanBateman @theRealAph 
I will look to create more examples.

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

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