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

[jbduncan]

Hi @33epico, it's not clear to me how much experience you have with Java, but I think this issue in which @JingMa87 asked a similar question may prove to be a good starting point for you.

If after reading it you're still confused or have any specific questions, please feel free to raise a new issue, and I'm sure someone can give you more information on finding your way in the world of open source development. :)

[33epico]

thanks a lot @jbduncan I just read the @JingMa87 post and its ok, Im gonne to read the documentation and start using the Junit5 to know it at all.

Regards!!

[JingMa87]

Good luck @33epico! 😄

[amirhmd]

Hi there, anybody could tell me how can i contribute in this project?
thanks in advance,
Amir

[jbduncan]

Hi @amirhmd, welcome!

I'd personally recommend you read through this issue first, where I suggested a bunch of (hopefully) useful starting points for contributing to JUnit 5.

If, after reading through it, you're still not clear on what or how you could contribute, then please feel free to ask for more help by commenting here again or raising a new issue.

(You could even say something as simple as "Sorry, I'm still confused on what I can do to contribute to JUnit 5, so can I have some more help please?", and that would be perfectly fine!)

Hope this helps. :)

[sbrannen]

FYI: @sormuras and I have put together a proof of concept (PoC) for generating reports on declarations of @API within a given project (potentially across multiple modules).

The PoC is capable of generating snippets for inclusion in Markdown, Asciidoc, and HTML documents.

An example of the generated Markdown can be seen here: #856 (comment) (note: you have to expand the Details section in the comment).

An example of the generated Asciidoc can be seen here: http://junit.org/junit5/docs/snapshot/user-guide/#api-evolution-experimental-apis

And the code that generates these snippets can currently be found here: https://github.com/junit-team/junit5/tree/master/platform-tests/src/test/java/org/junit/api/tools

[sbrannen]

Closing this issue in favor of apiguardian-team/apiguardian#2.

Please continue the discussions there.