Skip to content

7903866: apidiff: add an example to the doc #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

7903866: apidiff: add an example to the doc #26

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1cffc32
Add an example
Oct 16, 2024
74f197f
Add an example
Oct 20, 2024
249c1bb
Add an example
Oct 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions src/share/doc/apidiff.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -497,3 +497,20 @@ The tool does _not_ attempt to run `javadoc` locally to generate the page on the
[jdk.compiler]: https://docs.oracle.com/en/java/javase/17/docs/api/jdk.compiler/module-summary.html
[Java Language Model API]: https://docs.oracle.com/en/java/javase/17/docs/api/java.compiler/javax/lang/model/package-summary.html
[Compiler Tree API]: https://docs.oracle.com/en/java/javase/17/docs/api/jdk.compiler/com/sun/source/doctree/package-summary.html

## Example

To compare APIs in the `java.base` module in JDK builds `/local/baseline-jdk` and `/local/updated-jdk`, and place the result in the directory `out`, run the following command:

```
bin/apidiff \
--api jdk \
--jdk-build /local/baseline-jdk/build/linux-x86_64-server-fastdebug \
--api sv \
--jdk-build /local/updated-jdk/build/linux-x86_64-server-fastdebug \
--jdk-docs docs \
-d out \
--compare-api-descriptions true \
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@jonathan-gibbons jonathan-gibbons Oct 21, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Will you approve this one, please?

--include 'java.base/**'
```