[JSR308] Section 3.5, syntax of array annotations

[Bill Pugh]

JSR305 will provide a @Nonnull annotation so that you can declare,  
using Java 5,

@Nonnull Document [] nnarray_of_docs;

Under JSR305 running on Java 5, this will be interpreted as being  
that nnarray_of_docs is a nonnull reference to an array of possibly  
null references to Documents.

Thus, proposal (1) is unacceptable, since it would change this  
interpretation.


Overall, all of the proposals for array syntax annotations are  
horrible complicated and I worry about whether people would apply/ 
interpret them correctly. It may be that the syntax/problem is so  
nasty that you can't some up with a solution that is most developers  
could correctly use most of the time, and so you just shouldn't bother.

Anyway, the annotation you are going want to use most frequently on a  
multidimensional array is

@Matrix double [][] data;

which indicates that data is a rectangular unaliased and unchanging  
matrix.

If you want to do something for arrays, I'd encourage attemping  
something simplier: just come up with a way to annotate the element  
at the bottom of the array nesting. For example,

@Nonnull int [] @Nonnegative data;

to represent a nonnull reference to an array of nonnegative integers.  
While

@Nonnegative int [] @Nonnull data;

might make a little more sense, we can't use it since it won't be  
compatible with pre-Java7 uses of annotations.