CodeTools proposal: apidiff

Kumar Srinivasan kusrinivasan at
Fri Jan 15 18:05:42 UTC 2021


The old internal tool was far from optimal.


> On Jan 8, 2021, at 10:55 AM, Jonathan Gibbons <jonathan.gibbons at> 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]:
> [records]:
> [sealed classes]:
> [compatibility]:
> [binary compatible]:
> [java-diff-utils]:
> [daisydiff]:

More information about the code-tools-dev mailing list