anomaly with apidiff output

[Jonathan Gibbons]

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://github.com/openjdk/jdk/compare/master...stuart-marks:jdk:JDK-8138614-relax-new-string-requirement 
>
>
> 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
>