Re: [weld-dev] Goals for JavaDoc

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 > > > > >