Help

Built with Seam

You can find the full source code for this website in the Seam package in the directory /examples/wiki. It is licensed under the LGPL.

JavaDoc Guidelines

The following guidelines are intended primarily for the public API. The JavaDoc on internals does not necessarily have to be as details.

The goal is that people should be just about able to use things from just reading JavaDoc. It doesn't 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.