7903866: apidiff: add an example to the doc

[theRealAph]

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

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issue

• CODETOOLS-7903866: apidiff: add an example to the doc (Enhancement - P4)

Reviewers

• Jonathan Gibbons (@jonathan-gibbons - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/apidiff.git pull/26/head:pull/26
$ git checkout pull/26

Update a local copy of the PR:
$ git checkout pull/26
$ git pull https://git.openjdk.org/apidiff.git pull/26/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 26

View PR using the GUI difftool:
$ git pr show -t 26

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/apidiff/pull/26.diff

Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back aph! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@theRealAph This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

7903866: apidiff: add an example to the doc

Reviewed-by: jjg

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 1 new commit pushed to the master branch:

• 01d14ee: 7903870: add info about return codes (exit codes) to man page

Please see this link for an up-to-date comparison between the source branch of this pull request and the master branch.
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@jonathan-gibbons) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

[mlbridge]

Webrevs

• 02: Full - Incremental (249c1bb7)
• 01: Full - Incremental (74f197f9)
• 00: Full (1cffc32a)

[jonathan-gibbons]

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

[theRealAph]

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.

[jonathan-gibbons]

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.

[theRealAph]

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.

[AlanBateman]

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.

[jonathan-gibbons]

@AlanBateman @theRealAph
I will look to create more examples. At least part of the problem is the variety of ways that people might create the two instances of a build to be compared. For example, one can use two different repos, each with their own build (that has been my personal preference), or two different git workareas, or two differently named build configurations within the same repo.

It also didn't help that there was a bug in the version that people first started using, causing them to try weird command-line combinations to work around the bug. That bug has now been fixed.

[theRealAph]

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

Will you approve this one, please?

[jonathan-gibbons]

My intent is to develop a section in the doc containing real, verified examples (backed up by some form of test script.) My thought is to start with the smallest command-line for testing 2 JDK builds, and to build up from there. I'd like to illustrate that the command line is not that complicated! You should have seen it before the --jdk-build option was introduced.

That all being said, it will take a (short) while to develop that update, so I'll approve this example as either an interim measure or as part of what is to come.

[theRealAph]

My intent is to develop a section in the doc containing real, verified examples (backed up by some form of test script.) My thought is to start with the smallest command-line for testing 2 JDK builds, and to build up from there. I'd like to illustrate that the command line is not that complicated! You should have seen it before the --jdk-build option was introduced.

That all being said, it will take a (short) while to develop that update, so I'll approve this example as either an interim measure or as part of what is to come.

OK, thanks. Regardless of other sections in the docs with real, verified examples, it's still a really good idea to have a few simple examples at the end of the man page. Such examples help by effectively tying the long list of options to something more concrete.

[theRealAph]

/integrate

[openjdk]

@theRealAph
Your change (at version 249c1bb) is now ready to be sponsored by a Committer.

[jonathan-gibbons]

/sponsor

[openjdk]

Going to push as commit 3495601.
Since your change was applied there has been 1 commit pushed to the master branch:

• 01d14ee: 7903870: add info about return codes (exit codes) to man page

Your commit was automatically rebased without conflicts.

[openjdk]

@jonathan-gibbons @theRealAph Pushed as commit 3495601.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.