Filip

How about a common extension interface, that would allow to add some metadata API declaration. This could be an additional entry point for external tools that would like to work...

The most primitive extension interface would be tagging: ``` @interface API { /** (...) */ Status status(); /** (...) */ String since() default ""; /** (...) */ String[] consumers() default...

I like this idea. I can imagine some build tool plugins that would validate these restrictions. Not sure though whether it should be the same plugin as the one proposed...

Most of these are somehow similiar to `INTERNAL`, but I'd say that this is a different perspective. While `API.Status` only describes the lifecycle of API, these methods describe expected behaviour...

@sbrannen I wouldn't agree. These are 2 different perspectives - `@API` describes high-level contract about interface of the artifact, while `@NoReference` is used in context of a single class. Also:...

Yes. I only argued that `INTERNAL` isn't **exact** equivalent of `@NoReference`. They may overlap, but are not replacable in 1-1 relation.

Huh... I think that the word "used" is the source of misunderstanding here. From my perspective such repo implementations (as well as e.g. SOAP service implementations, etc) are purely internal...

I totally agree and I would have provided almost identical example. I agree that `Cat` can be annotated with `INTERNAL` status, but by calling `create()` you'll obtain reference to `Cat`...

> Classes, interfaces, annotations, enums, methods and fields tagged with this annotation are declaring they are not to be **referenced** at all by clients. OK, so this is yet another...

OK, now we're on the same page. All this time I was defending this annotation as non-breaking DRY, because I understood "referencing" as "referencing in runtime". Would we understand that...