[type-annos-observers] JLS and JVMS changes for JSR 308

[Alex Buckley]

I have prepared a PDF containing the JLS and JVMS changes for JSR 308:

   http://cr.openjdk.java.net/~abuckley/308.pdf

If you're expecting a simple list of grammar changes, you may want to 
sit down before opening the PDF. There are significant clarifications to 
JLS chapters 4 and 6, all aimed at pinning down what exactly is a type 
use. The JLS has distinguished between types (a.k.a. type uses) and type 
names since JLS3, but it was very subtle, and it is essential for JLS8 
to take a comprehensive view of the language's syntactic contexts and 
the types and names allowed therein.

The ClassFile changes present a recurring challenge: how much to mention 
Java language features in the JVMS? The Signature attribute is a 
precedent, so for now, I have aimed for maximum clarity. An example 
would be mentioning both constructors and methods when describing 
target_info, even though the ClassFile structure is aware only of methods.

Text in the PDF is either normative or informative. Informative text is 
smaller and indented. The point of the PDF is that most text is ready to 
go into the JLS or JVMS as-is, although informative text which mentions 
JSR 308 is intended more as commentary for 2013 than as long-term 
specification; it will evolve further, or be removed.

The UW PDF at:

 
http://types.cs.washington.edu/jsr308/specification/java-annotation-design.pdf

remains an excellent source of background, examples, and rationale. This 
kind of material should be available on the JSR 308 page at jcp.org 
forever, so I envisage offering both 308.pdf and 
java-annotation-design.pdf in the milestone reviews yet to come.

Mike, it would be instructive to look at how JSR 334's specification 
changed between Public Review and Proposed Final Draft. Vast swathes of 
normative text were replaced with pointers to JLS sections. It would be 
appropriate to start the same "pruning" process on 
java-annotation-design.pdf. This will provide a double check on my 
extraction of normative clauses from java-annotation-design.pdf.

Alex