[External] : Re: anomaly with apidiff output

[Stuart Marks]

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