CodeTools proposal: apidiff

Sat Jan 16 01:19:08 UTC 2021

I'll be asking the OpenJDK admins next week to set up a repo for this.

-- Jon

On 1/15/21 10:05 AM, Kumar Srinivasan wrote:
> +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://urldefense.com/v3/__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__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJQ!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9OIqo7hjQ$
>> [records]: https://urldefense.com/v3/__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__;JSUlJSUlJSUlJSUlJSUlJSUlJQ!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9P64C7t7g$
>> [sealed classes]: https://urldefense.com/v3/__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__;JSUlJSUlJSUlJSUlJSUlJSUlJQ!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9MX9FDCtw$
>> [compatibility]: https://urldefense.com/v3/__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__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJSU!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9NUTDlw2w$
>> [binary compatible]: https://urldefense.com/v3/__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__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJSUl!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9NpwKYOIA$
>> [java-diff-utils]: https://urldefense.com/v3/__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__;JSUlJSUlJSUlJSUlJSUlJSUl!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9MJUKeIoA$
>> [daisydiff]: https://urldefense.com/v3/__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__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJSU!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9Mt4ccBpA$
>>
>>
>>