CodeTools proposal: apidiff

[Jonathan Gibbons]

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://openjdk.java.net/projects/amber/
[records]: https://openjdk.java.net/jeps/395
[sealed classes]: https://openjdk.java.net/jeps/360
[compatibility]: 
https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility
[binary compatible]: 
https://docs.oracle.com/javase/specs/jls/se15/html/jls-13.html
[java-diff-utils]: https://github.com/java-diff-utils/java-diff-utils
[daisydiff]: https://code.google.com/archive/p/daisydiff/