[External] : Re: anomaly with apidiff output

Mon Mar 10 00:28:43 UTC 2025

Stuart,

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. Also note that while there has been much 
work to standardize how to locate the basic HTML description for an 
element (in terms of HTML elements, and class and id attributes) there 
is no such internal/informal standard for the presentation of the 
signature of the element, which is the closest approximation in the HTML 
to the Language Model element.

Yes, there are other API comparison tools that just try and compare the 
generated HTML documentation.

Assuming you are typically comparing the API in different JDK builds, I 
highly recommend  using the `--jdk-build` API option. If that doesn't 
address your needs, let me know, and I'll see if I can come up with 
additional suggestions for you.

You might find it instructive to review the presentation I gave last 
summer; I'm assuming you can find the saved PDF. If not, contact me 
privately.

-- Jon

On 3/8/25 11:04 AM, Stuart Marks wrote:
> Hi Jon,
>
> Good to hear from you!
>
> I guess I've been operating under the assumption that apidiff works 
> (or can work) by gathering all the information from two versions of 
> the HTML javadoc output and generating the differences between them. 
> (That's the way specdiff works and how I've been using it for quite 
> some time.)
>
> If apidiff doesn't work that way, then ok, I'll figure out a different 
> approach.
>
> I guess what's surprising to me is that it *almost* works. It 
> successfully found the two classes that were impacted and found and 
> displayed the correct diffs for one of the classes but not the second. 
> And the second class is *mostly* there but some bits are missing. So 
> it seems to me like there's just some bug there that's preventing it 
> from working completely, and not a fundamental problem with the model 
> of comparing HTML javadoc output.
>
> I haven't looked at the code, though, so it's entirely possible that 
> I'm way off base on this.
>
> I'll try out some alternative approaches for generating the diffs that 
> I'm looking for. Thanks for your suggestions.
>
> s'marks
>
>
>
> On 3/6/25 8:31 AM, Jonathan Gibbons wrote:
>> Stuart,
>>
>> Without deep-diving too much too quickly, your command line seems to 
>> be incomplete.
>>
>> It is not enough to *just* provide the api directory; you need to 
>> provide the source and/or class files as well. When comparing JDK 
>> docs, this is best done by using the `--jdk-build` option, which 
>> internally expands to the appropriate javac-level options.
>>
>> 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.
>>
>> -- Jon
>>
>> On 3/5/25 2:11 PM, Stuart Marks wrote:
>>> Hi Apidiff Devs,
>>>
>>> I'd like to report an anomaly with apidiff. I made a recent change 
>>> to the JDK specification, which can be seen here:
>>>
>>>
>>> https://urldefense.com/v3/__https://github.com/openjdk/jdk/compare/ 
>>> master...stuart-marks:jdk:JDK-8138614-relax-new-string-requirement__;!! 
>>> ACWV5N9M2RV99hQ!Nttbo- 
>>> eq1OfDZAq3juoWytRGuIZooffq5gUBLSrnn8NoGzFg2OV7PVk7szakD5cgg1xlxKC7RcLUjg$
>>>
>>> This is a change to the doc comments of four AbstractStringBuilder 
>>> methods: subSequence, substring(i), substring(i, i), and toString(). 
>>> Note that ASB is a non-public class which has two public subclasses, 
>>> StringBuffer and StringBuilder. Thus there should be a total of 
>>> eight changes: four methods in each of the two public classes.
>>>
>>> I did two javadoc runs: one on the tip of this branch ("new") and 
>>> one for its right parent which is the commit from master that was 
>>> merged into it ("old"). The diffs are minimal. The javadoc output is 
>>> as expected: I can see changes in the specs of four methods in each 
>>> of the StringBuilder and StringBuffer classes.
>>>
>>> I build apidiff from source a couple weeks ago. The command line I 
>>> ran was something like:
>>>
>>>     apidiff --api old --api-directory javadoc-old \
>>>         --api new --api-directory javadoc-new \
>>>         --include 'java.base/java.lang.*' --output-directory sb.apidiff
>>>
>>> (Where javadoc-old and javadoc-new are the respective javadoc output 
>>> directories.) It seemed mostly successful in that it inspected all 
>>> the java.lang classes, and it found differences in the right files.
>>>
>>> The output is visible here:
>>>
>>>     https://cr.openjdk.org/~smarks/misc/sb.apidiff/
>>>
>>> However, the actual differences it found were incorrect. The diffs 
>>> for StringBuffer seem correct. However, for StringBuilder, only one 
>>> difference is shown, for the toString() method. The diffs for the 
>>> other methods are missing. Also, perhaps significant, is that a 
>>> couple other methods are missing from StringBuilder, setCharAt() and 
>>> setLength(), though there aren't any differences in the specs of 
>>> these methods.
>>>
>>> Daniel Fuchs suggested that 
>>> https://bugs.openjdk.org/browse/CODETOOLS-7903843 might be related. 
>>> Indeed it might be, but I can't tell.
>>>
>>> Anyone have any ideas? I can file a bug with this info if it's helpful.
>>>
>>> s'marks
>>>
>