David just asked me about exactly what I want from the Javadoc. Here's a rough guide: The goal is that people should be just about able to use things from just reading javadoc. It doesnt need to baby people, or explain things that are not directly relevant to the particular annotation, or go into very technical definitions, but it should contain all the information about: * what the annotation or interface is for, * how it is used, * what other annotations or interfaces it is used together with, * what its behavior is, and * the example(s) of its use. If the user has to go digging about in the spec to figure out what an annotation does, they are already wasting time and they will already think 299 is "hard". Our goal is that reasonably sophisticated users should be able to get up and running with this stuff *without* needing additional docs. Note that the *.spi packages do not need to be documented at quite the same level as the application-developer-visible stuff. -- Gavin King gavin.king(a)gmail.com http://in.relation.to/Bloggers/Gavin http://hibernate.org http://seamframework.org

Gavin, Do you think we should also write BNF for the annotations as is done with JSR-330?  I think most will appreciate examples better, but for those with some CS background, the BNF is always clear too.  I'm undecided myself whether it is worth it or not. - David On Fri, 2009-10-23 at 02:08 -0400, Gavin King wrote: > I did a first rev of the javadoc for the package javax.decorator. Take a look. > > Not perfect, by any means, but its a good start. Note that I basically > just copied and pasted out of the spec, and then massaged a little > bit. > > On Thu, Oct 22, 2009 at 11:32 AM, Gavin King <gavin.king(a)gmail.com&gt; wrote: > > David just asked me about exactly what I want from the Javadoc. Here's > > a rough guide: > > > > The goal is that people should be just about able to use things from > > just reading javadoc. It doesnt need to baby people, or explain things > > that are not directly relevant to the particular annotation, or go > > into very technical definitions, but it should contain all the > > information about: > > > > * what the annotation or interface is for, > > * how it is used, > > * what other annotations or interfaces it is used together with, > > * what its behavior is, and > > * the example(s) of its use. > > > > If the user has to go digging about in the spec to figure out what an > > annotation does, they are already wasting time and they will already > > think 299 is "hard". Our goal is that reasonably sophisticated users > > should be able to get up and running with this stuff *without* needing > > additional docs. > > > > Note that the *.spi packages do not need to be documented at quite the > > same level as the application-developer-visible stuff. > > > > > > > > -- > > Gavin King > > gavin.king(a)gmail.com > > http://in.relation.to/Bloggers/Gavin > > http://hibernate.org > > http://seamframework.org > > > > >

Here's a rough guide: The goal is that people should be just about able to use things from just reading javadoc. It doesnt need to baby people, or explain things that are not directly relevant to the particular annotation, or go into very technical definitions, but it should contain all the information about: * what the annotation or interface is for, * how it is used, * what other annotations or interfaces it is used together with, * what its behavior is, and * the example(s) of its use. If the user has to go digging about in the spec to figure out what an annotation does, they are already wasting time and they will already think 299 is "hard". Our goal is that reasonably sophisticated users should be able to get up and running with this stuff *without* needing additional docs. Note that the *.spi packages do not need to be documented at quite the same level as the application-developer-visible stuff.