Introduce tools for @API annotation processing

[jlink]

Do something useful with @API annotations, e.g.

• Extract all public APIs
• Compare two versions of JUnit 5 for release notes
• Check correct usage of APIs (internally and externally)

[sbrannen]

FYI: this issue is related to #436.

[smoyer64]

As noted in PR #564, I've started working on a small set of tools to perform the functions listed above. As I've been working through that code, I found that I have a few more questions:

• Should @API also be applied to protected-scoped and package-scoped elements as well as publicly-scoped elements? I can argue both ways on this one but if the policy is that you only use public fields, methods, constructors that are not annotated with Usage.INTERNAL (or Usage.EXPERIMENTAL/Usage.DEPRECATED at your own risk), then it's relatively safe to assume the elements needed are going to be public.
• It's clearly stated that if an element isn't annotated explicitly with @API, it's inherited from the enclosing class. I'll also walk the inheritance hierarchy to find the annotation if needed. But what about methods and constructors that are @OverRide? I think one of the important uses of @API is to encourage extension authors to continue to use @API but the application of the annotation will need to be unambiguously define. The implementation of interfaces in some ways recreates the "diamond problem" for @API.

[marcphilipp]

Should @API also be applied to protected-scoped and package-scoped elements as well as publicly-scoped elements?

There's (at least) two ways to look at it: (1) protected-/package-scoped elements are implicitly annotated with @API(Internal), or (2) we only look at public elements. I think either way, the outcome is the same, right?

It's clearly stated that if an element isn't annotated explicitly with @API, it's inherited from the enclosing class. I'll also walk the inheritance hierarchy to find the annotation if needed. But what about methods and constructors that are @OverRide?

I think we should enforce that an overridden method needs to explicitly re-declare an @API annotation.

@junit-team/junit-lambda What do you think?

[smoyer64]

@marcphilipp

I think we should enforce that an overridden method needs to explicitly re-declare an @API annotation.

As I've gotten a bit deeper into this coding, I agree that explicitly overridden methods should re-declare the @API annotation. This should also apply to interface method implementations as it eliminates a form of "the diamond problem".

I was hoping to be able to "lint" M3 but I'm not sure I'll finish in time for that.

[33epico]

Hi all:

I just finish muy java SE study, I would like to help and learn in any open source project. I just arrive here surfing the web and I am a little bit lost. Please anybody can give to me a path to help in this kind of proyects.

Thanks in advance