[External] : Re: anomaly with apidiff output

[Stuart Marks]

On 3/9/25 5:28 PM, Jonathan Gibbons wrote:
> With respect, you're way off base here.
> 
> apidiff uses the declarations in the source and class files to perform a structural 
> comparison using the Language Model API (JSR269) available to `javac` plugins and 
> extension classes. Having determined the declarations to be compared, and having 
> compared the underlying elements, it will then optionally in addition try and locate 
> the generated API documentation to run a comparison of the HTML description 
> generated by javadoc.
> 
> There is not sufficient information in the HTML files to fully reverse engineer the 
> Language Model elements that can otherwise be obtained using the `javac` front end. 

OK, fair, I remember you saying this, and the docs imply that the sources and class 
files are required. That said, since apidiff seemed to accept the javadoc HTML 
output, I figured I'd give it a try, and it looked like it allllmost worked....

But I understand that making it work in this mode (using only HTML as input) is 
probably untenable in the general case, and that's fine. Previously, you had said:

> If you do not provide the necessary options, the tool will fall back to using the platform classes. Maybe there is a way to enhance the command-line analysis to warn when the set of given options look at lest superficially insufficient.

Yes, it seems like that would be good.

***

Anyway, that aside, I took your advice and instead ran apidiff, providing it with 
sources and class files. I did two full JDK builds that differed only in the spec 
changes to AbstractStringBuilder, which would produce changes only in the javadoc 
output of StringBuilder and StringBuffer. The command line was something like this:

$ apidiff --api old --jdk-build jdk-tmp-a/build/macosx-aarch64 \
     --module-source-path jdk-tmp-a/open/src/java.base/share/classes/ \
     --api new --jdk-build jdk-tmp-b/build/macosx-aarch64 \
     --module-source-path jdk-tmp-b/open/src/java.base/share/classes/ \
     --include 'java.base/java.lang.*' --output-directory apidiff.out

And the output was pretty much the same as previously. That is, I got a nice report 
showing differences in StringBuffer and StringBuilder. StringBuffer had the correct 
differences in four methods, and StringBuilder was missing some method declarations 
(both changed and unchanged) and showed diffs only in the toString() method.

For reference, here's the previous output:

     https://cr.openjdk.org/~smarks/misc/sb.apidiff/

I could upload the new output but it's essentially the same to my eye.

Before going further, is this the right way to invoke apidiff?

s'marks