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.