[type-annos-observers] Constraining type annotations to occur just before type

[Markus Keller]

Since TYPE_USE is new in SE 8, this whole discussion is not about 
traditional source compatibility when moving from SE n to SE n+1. Of 
course, all SE 7 code still needs to compile unchanged in SE 8. And I'm 
not proposing anything that would affect this scenario.

The discussion is only about annotation types that are changed by adding 
TYPE_USE as target. Compare this to a parameterized type: Adding another 
type parameter is a breaking change. The provider of the type can do it, 
but its users must face the consequences.

> It's not ideal, but the alternative of breaking source compatibility is 
> worse. All a new SE 8 annotation processor (that is, a processor which 
> uses the new SE 8 reflection methods) has to do - until such time as the 

> annotation type's provider makes TYPE_USE the sole target - is detect 
> that NonNull is a legacy annotation type and react accordingly.

Removing a declaration target from an existing annotation is always a 
breaking change. Old annotation types better make a clear cut and break 
compatibility now, rather than trying to stay compatible with old versions 
and only break their clients in a later release.

> > The superficially supported combination of TYPE_USE and declaration 
targets
> > creates horrible corner cases for every user of such an annotation 
(even
> > those who only started to use them with SE 8 or later).
> 
> No! Not for "every user" of an annotation. Be precise, please. It 
> creates corner cases for the handful of people who write annotation 
> processors. Everyone who applied the annotation is fine.

No, it not only affects writers of annotation processors. Since the 
annotation processor has to implement convoluted semantics, it also 
affects people who just want to apply the annotation. Not every user may 
run into the corner cases immediately, but the corner cases are there for 
every user.

> No, the language should not seek to organize different kinds of 
> annotations. An annotation type like NonNull has semantics - 
> specifically regarding inheritance, repeatability, and targetability - 
> but an @NonNull annotation has no meaning in the language so the 
> language should not prescribe whether it appears before or after 
> 'public'.

All type-use annotations share one part of their semantics: They belong to 
the annotated type.

> The JLS can certainly _recommend_ that type annotations appear 
> in one place and declaration annotations appear somewhere else, but 
> enforcement is a matter for tools.

Just because type-use annotations look the same as declaration annotations 
doesn't mean they have to be treated the same. Like the JLS forces me to 
write modifiers in front of the type of a field (and not e.g. in front of 
the field name, which would be easily acceptable for a parser), it can 
also enforce annotation positions. 


It all boils down to the question whether adding TYPE_USE should be 
considered a compatible change or not.
- pro "incompatible": avoid the mentioned inconsistencies and be free to 
add helpful positional restrictions
- pro "compatible": try to be helpful to providers (and users) of 
annotations that abused declaration annotations as type-use annotations 
and now try to get away without source changes

I value a consistent story higher.

Regards,
Markus Keller
IBM Rational Zurich Research Lab
Eclipse JDT UI lead