[External] : Re: anomaly with apidiff output

[Jonathan Gibbons]

If you use `--jdk-build` you typically don't need to set any other 
javac-like options, including `--module-source-path`. `--jdk-build` will 
automatically use the source files in the `src.zip` in the given build. 
The only reason that may not be enough would be if you are wanting to 
compare any classes whose sourcs is not in src.zip -- yes, some files 
might be omitted in certain situations, but that's a different, more 
complicated story.

-- Jon


On 3/11/25 2:20 PM, Stuart Marks wrote:
>
>
> 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
>