<div class="gmail_quote">On Thu, Oct 22, 2009 at 11:32 AM, Gavin King <span dir="ltr"><<a href="mailto:gavin.king@gmail.com">gavin.king@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Here's a rough guide:<br>
<br>
The goal is that people should be just about able to use things from<br>
just reading javadoc. It doesnt need to baby people, or explain things<br>
that are not directly relevant to the particular annotation, or go<br>
into very technical definitions, but it should contain all the<br>
information about:<br>
<br>
* what the annotation or interface is for,<br>
* how it is used,<br>
* what other annotations or interfaces it is used together with,<br>
* what its behavior is, and<br>
* the example(s) of its use.<br>
<br>
If the user has to go digging about in the spec to figure out what an<br>
annotation does, they are already wasting time and they will already<br>
think 299 is "hard". Our goal is that reasonably sophisticated users<br>
should be able to get up and running with this stuff *without* needing<br>
additional docs.<br>
<br>
Note that the *.spi packages do not need to be documented at quite the<br>
same level as the application-developer-visible stuff.<br></blockquote><div><br>I added these points here: <a href="http://seamframework.org/Weld/GuidelinesForWeldDevelopment#H-JavaDocGuidelines">http://seamframework.org/Weld/GuidelinesForWeldDevelopment#H-JavaDocGuidelines</a><br>
<br>This is a great goal. Many users have been asking for this, not just in JSR-299/Weld but in Seam too.<br><br>-Dan </div></div><br>-- <br>Dan Allen<br>Senior Software Engineer, Red Hat | Author of Seam in Action<br>Registered Linux User #231597<br>
<br><a href="http://mojavelinux.com">http://mojavelinux.com</a><br><a href="http://mojavelinux.com/seaminaction">http://mojavelinux.com/seaminaction</a><br><a href="http://www.google.com/profiles/dan.j.allen">http://www.google.com/profiles/dan.j.allen</a><br>