All methods should be commented, with the following exceptions:

Parameters and return values should be identified. @throws should identify when any checked exceptions are thrown; additional @throws entries should describe any runtime exceptions that may also be thrown.

Methods should always include a @since entry, unless the method was added as part of a new Java class or interface, in which case the @since for the containing type is sufficient. Use the same version number as type comments when adding individual methods.

Try not to skimp on the comment (it is often best to write the comment before writing any code). Tapestry has some of the best documentation of any open source project and that should be maintained. Remember to try and answer the question why?, which is always much more interesting and useful than how? or what?.

It is appropriate to create JavaDoc comments for variables, even private variables (to at least provide an @since value).

Collections (from package java.util) should be documented to identify the type of object stored, and for Map the type of key. Example: List of {@link IRender}, or Map of {@link IBinding} keyed on String name.

When a method returns a collection type, the documentation should indicate if it is safe for the caller to modify the collection or not. In general, it is best to always return an immutable copy of a collection, but for efficiency this is not always reasonable.

Also document any cases where a parameter is allowed to be null, or a return value may be null.

And don't forget to make liberal use of JavaDoc links (@link) which makes the documentation far easier to use.