Self Documenting Code

Sun have provided a documentation tool, JavaDoc. This utility reads Java source files, and automatically produces documentation for the classes within them.

If a Java comment block immediately before a public class or method declaration begins with /** (rather than just /*) then JavaDoc will extract the text of the comment into the documentation.

JavaDoc can also extract certain key fields from these comment blocks:

   @author
   @version
   @param

This is a highly recommended way of allowing all class interfaces to be automatically documented.