Non-public types should have @API(Internal)

[smoyer64]

Overview

• (X) Consistency.

The javadocs for @API states:

Annotates public types within JUnit to indicate their level of stability and how they are intended to be used. If the annotation is present on a type, it is considered to hold for all public members of the type as well. A member is allowed to declare a different API.Usage of lower stability.

It occurs to me that a public class with only non-public constructors is effectively internal whether or not the API annotation says so. Classes in this state could however have public static members with API annotations that are not internal-only.

Clarifying the precise rules for the API annotations use is important for the completion of #144 (which I intend to return to when I'm done with #343). One additional question is whether @API(Internal) types should show up in the "developer javadocs" (#676).

There are currently classes with package access-levels that are marked as @API(Experimental) - I've mostly noticed them in the org.junit.jupiter.engine.discovery package:

• JavaElementsResolver
• MethodFinder
• TestContainerResolver
• TestFactoryMethodResolver
• TestMethodResolver

Deliverables

• Clarify @API usage.
• Mark non-public classes as @API(Internal)

[marcphilipp]

Our original intent was to mark classes that are visible to third-party code (i.e. classes declared as public) with @API. All other classes are invisible and therefore do not need to be marked as @API(Internal). Why should we mark them?

[smoyer64]

That sounds like a great clarification to the API usage and can certainly be codified into the API tools. If you take a look at JavaElementsResolver, it's not public and has no public members, yet it's marked as @API(Experimental). If I understand what you're saying correctly, that class should either have the @API(Internal) annotation or it should have the API annotation removed altogether.

If it's marked as experimental because it's not finished yet, that's more of a status than a usage. In any case, I should have some tools ready to try out on the API annotations by mid-March. Thanks for helping me better understand what the API tools should be reporting!

[marcphilipp]

I think it's marked as experimental by mistake. Maybe it was public during development and the annotation was simply forgotten when the public keyword was removed. Having an API tool check for such illegal usage patterns would be great... 😉

Edit: I replaced "default" with "mistake" in the first sentence.

[mkobit]

This seems done with the 5.0.0/1.0.0 releases?

[marcphilipp]

Yes, I've opened apiguardian-team/apiguardian#2 to create a validation check for non-public types/methods.