Add support for named APIs

[odrotbohm]

Some projects might want to expose different sets of APIs to be able for downstream process to define that they are allowed to depend on API Foo, while such a project might expose a set of types Foo and another set of types Bar. It would be nice if @API got an additional, optional String[] attribute name, so that multiple types or packages annotated with @API(name = "foo") would all belong to the API foo. name containing multiple attributes would assign a type or package to multiple named APIs.

[whiskeysierra]

Custom meta annotations would be nice instead of raw strings, e.g.

@API
@Target({ TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE })
@Retention(RUNTIME)
@Documented
public @interface MyAPI {

}

@API
@Target({ TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE })
@Retention(RUNTIME)
@Documented
public @interface MyOtherAPI {

}

Instead of using @API on your public types etc., you'd use either of those two (or maybe both even).

[odrotbohm]

I still think a simple name attribute would be nice, as it is so much more concise than having to define a new annotation for each named API and all the questions that introduces (where, i.e., which package, those annotations live (in)).

Furthermore, the usage of @API here is outside the scope of its current semantics: you are assuming that any type carrying an annotation itself annotated with @API is supposed to be considered API immediately when the author of that custom annotation just wanted that annotation to be declared API within a codebase. The specification of @API currently is unclear about that, but I think that the semantics you assume are not what current users anticipate. For example, JUnit's usage of @APIon lifecycle method annotations (@AfterEach, etc.) hopefully do not extend into a declaration that those methods are considered API of the user project implicitly.