Introduce tools for @API annotation processing

[marcphilipp]

Ideas

• Extract all public APIs and generate a report
• Compare two versions of an artifact for release notes
• Check correct usage of APIs (internally and externally)
  • The tool should check that @API is only declared on public types/methods.
• Implement a reporting tool that warns about usage of experimental and deprecated APIs.
  • See jdeprscan from JDK 9 for inspiration.

Related Issues

• Introduce tools for @API annotation processing junit-team/junit5#144

Deliverables

• ?

[sbrannen]

Update: moved ideas from junit-team/junit5#144 to here.

[sbrannen]

Added link to jdeprscan.

[sormuras]

A compiler plugin could be useful: http://www.baeldung.com/java-build-compiler-plugin

[FilipMalczak]

I've started writing an approach to this. I've mentioned the general idea here. Instead of plugging into compiler, I intend to extract API descriptor with Google Reflections (I had an approach to Scannotation and gave up) and use it to perform validation and comparison.

You can follow the works here.

[FilipMalczak]

Check correct usage of APIs (internally and externally)

• The tool should check that @API is only declared on public types/methods.

What else can we check here? Do we consider internal classes as valid API?