[weld-dev] Goals for JavaDoc

[Dan Allen]

On Thu, Oct 22, 2009 at 11:32 AM, Gavin King <gavin.king at gmail.com> wrote:

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

I added these points here:
http://seamframework.org/Weld/GuidelinesForWeldDevelopment#H-JavaDocGuidelines

This is a great goal. Many users have been asking for this, not just in
JSR-299/Weld but in Seam too.

-Dan

-- 
Dan Allen
Senior Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://mojavelinux.com
http://mojavelinux.com/seaminaction
http://www.google.com/profiles/dan.j.allen
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/weld-dev/attachments/20091023/82ec4bf0/attachment.html