[weld-dev] Goals for JavaDoc

[Gavin King]

No, IMO the use of BNF in 330 is absurd.

A BNF is useful for formal specification of a language. The Java
language already has a formal specification, and the 299 annotations
are well-defined in terms of that formal specification. We don't need
to re-specify the syntax of Java in our javadocs.

On Fri, Oct 23, 2009 at 5:37 AM, David Allen <drallendc at gmail.com> wrote:
> 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
>> >
>>
>>
>>
>
>



-- 
Gavin King
gavin.king at gmail.com
http://in.relation.to/Bloggers/Gavin
http://hibernate.org
http://seamframework.org