Re: [weld-dev] Goals for 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.