CodeTools proposal: apidiff

[Kumar Srinivasan]

+1

The old internal tool was far from optimal.

Kumar


> On Jan 8, 2021, at 10:55 AM, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> On 1/8/21 10:48 AM, Jonathan Gibbons wrote:
>> This is a proposal for a new tool in the OpenJDK CodeTools project: apidiff.
>> 
>> I've attached Markdown and HTML versions of the proposal.
>> 
>> -- Jon
>> 
>> 
> 
> I guess the attachments didn't make it.  Here's the Markdown:
> 
> # Proposal: apidiff
> 
> Summary: A utility to compare two or more versions of an API, using a
> combination of the information in class files, source files and/or API
> documentation files.
> 
> ## Rationale
> 
> An important task when evolving APIs is to be able to compare different versions
> of an API, such as before and after a proposed change. However, comparing
> versions of an API is not an easy task:
> 
> * Comparing just source files is hard because of additional content related to
>   the implementation of the API.
> 
> * Comparing just class files is hard because class files do not include any
>   narrative specification from the documentation comments.
> 
> * Comparing just API documentation files is hard because the underlying model of
>   the API can be difficult to discern, and is subject to the presentation by the
>   `javadoc` tool. However, this is the form most commonly used by developers
>   wanting to read the specification of an API.
> 
> In addition, the Java language is [evolving][amber], with new features like
> [records][] and [sealed classes][], and it is desirable for comparison tools to
> be able to handle such features when they show up in an API.
> 
> It would also be good to be able to classify changes with respect to whether or
> not they are compatible changes, and if so,  what ["kind"][compatibility] of
> compatible. However, this generally requires detailed and accurate models of the
> APIs being compared: more so than can reasonably be obtained from API
> documentation files.
> 
> ## Description
> 
> `apidiff` is a tool that leverages the `javac` front end and other code in the
> JDK `java.compiler` and `jdk.compiler` modules in order to read source and/or
> class files, and to find the declarations to be compared. When source files are
> provided, the tool can also compare the "raw" documentation comments for those
> declarations, and if the corresponding API documentation is provided, the tool
> can also extract and compare the parts of the documentation for those
> declarations. Third-party libraries ([java-diff-utils][], [daisydiff][]) are
> used to compare the plain text of documentation comments and the relevant parts
> of the generated API documentation.
> 
> The tool can compare two or three versions of an API. It can compare classes
> on the class path, or in modules. It can also compare the often-overlooked
> specifications of the serialized forms of classes. It can compare classes in
> different versions of JDK, although there are currently limitations if
> preview features are involved. The tool requires JDK 11 or newer to run:
> because it uses JDK modules internally, the tool must be run with a version
> of JDK at least as new as the newest API being compared.
> 
> When comparing more than two versions of an API, the "structural" parts of
> each declaration are compared and reported as a group; the "narrative" parts
> of the specification of each declaration are compared pair-wise against the
> latest version.
> 
> Internally, the tool comprises a front end, which can set up and access
> different concurrent instances of the `javac` front end and which reports
> differences via an interface to a back end, which can generate an HTML report.
> An internal component provides the ability to extract the parts of an API
> documentation file containing the specifications of the declarations in that
> file, ignoring the "window dressing" of the header, footer, and summary tables;
> this component can handle the output generated by most recent versions of the
> `javadoc` tool.
> 
> 
> [amber]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fopenjdk.java.net%2Fprojects%2Famber%2F&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=wg1UC1WLaEIdzpy%2Fka0FSVUHI%2Fo8TnL5hRQE%2FQdLPYM%3D&reserved=0
> [records]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fopenjdk.java.net%2Fjeps%2F395&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=W81DltVfSDBzoIqaz71mHpLAd1%2BJRRaaNaDyiKLe8pU%3D&reserved=0
> [sealed classes]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fopenjdk.java.net%2Fjeps%2F360&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=jmq%2FHLf2psdCtl5apyObExF2zw0crouYCDkaO1nMYEs%3D&reserved=0
> [compatibility]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.openjdk.java.net%2Fdisplay%2Fcsr%2FKinds%2Bof%2BCompatibility&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=InfwdTKQvGsN%2BN06EuoAOSI373Giyn%2FZbfuxvI6XSjo%3D&reserved=0
> [binary compatible]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.oracle.com%2Fjavase%2Fspecs%2Fjls%2Fse15%2Fhtml%2Fjls-13.html&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=CrMmKF2rssvLU5ofpd3fZdE%2BOXuFcD%2BlVrAPTKg82UA%3D&reserved=0
> [java-diff-utils]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fjava-diff-utils%2Fjava-diff-utils&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=sxQZIyWCmbHuT8bCcFSf1uEHrs5w9MBFdrpDqqyGDp0%3D&reserved=0
> [daisydiff]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fcode.google.com%2Farchive%2Fp%2Fdaisydiff%2F&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=yjKHnQMegNUq5%2Bi4BTqX43t%2BqSRUfbpa0dZyGO3%2BzOI%3D&reserved=0
> 
> 
>