[weld-dev] Goals for JavaDoc

[David Allen]

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 at gmail.com> 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 at gmail.com
> > http://in.relation.to/Bloggers/Gavin
> > http://hibernate.org
> > http://seamframework.org
> >
> 
> 
>