[weld-dev] Goals for JavaDoc
Gavin King
gavin.king at gmail.com
Sat Oct 24 12:48:47 EDT 2009
OK, I've now also done all the annotations in javax.enterprise.inject
(but the Instance interface and exception classes are still to go).
Unfortunately a lot of important stuff had to live as package-level
doc :-/
I'm still just mainly copy/pasting and then reorging stuff from the spec.
I'm going to need help with the SPI packages and exception classes.
This stuff is *very* slow going...
On Fri, Oct 23, 2009 at 2:08 AM, Gavin King <gavin.king at gmail.com> 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
>
--
Gavin King
gavin.king at gmail.com
http://in.relation.to/Bloggers/Gavin
http://hibernate.org
http://seamframework.org
More information about the weld-dev
mailing list