Javadoc Guidelines

General Rules

All public and protected methods must have full documentation
Trivial getters and setters are exempted from this rule. Doing anything but returning or changing a variable in a getter or setter should be documented.
Private methods with non-obvious implementations should have enough documentation to allow other developers to debug them

Sun documentation

http://java.sun.com/j2se/javadoc/writingdoccomments/

Guidelines

package.html

Use the following template for writing package.html files. Generally write a package.html for any non-trivial package.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--

  @(#)package.html      $Id$ $Date$

  Copyright 2007 State and University Library Statsbiblioteket,
  All Rights Reserved.

  INSERT LICENSE HEADER HERE

-->
</head>
<body bgcolor="white">
<!--
    The first line should be a one sentence summary starting with a verb.
    Used in package overviews like :

       http://java.sun.com/j2se/1.5.0/docs/api/overview-summary.html
-->
Provides tools to build and digest Pies.

<h2>Purpose</h2>
The purpose of this package is to provide a robust extensible framework for building and digesting pies.
Speed and memory efficiency has been down prioritized and focus is primarily on providing a rock solid
platform.

<h2>Implementation</h2>
There are three interfaces of central interest in this package. {@link Pie}, {@link PieEater} 
and {@link PieFactory}. A sample implementation {@link RatPie} is provided as well. 
Here is a breakdown of the functionality:

<ul>
  <li>Foo</li>
  <li>Bar</li>
</ul>

<h2>Examples</h2>
To integrate pies in your own code start by defining a factory
<code>
FooBar
</code>
Blah di blah...

<h2>Related Documentation</h2>
The primary reference on pie theory is E. Idles famous article "The Pie and I" found below.
<ul>
  <li><a href="http://example.com">E. Idle, "The Pie and I"</a></li>
  <li>foo</li>
  <li>bar</li>
</ul>

<!-- Optionally put @see and @since tags down here. -->

</body>
</html>

Links

{@link MyClass#someMethod} should be written the first time someMethod is mentioned in the text. Subsequent mentions should not have links.

Generally use @link, @see and @seealso generously.

External links: You can use the standard <a href="http://example.com">example.com</a> syntax directly in the javadoc as well as in @see/@seealso and <a href="mailto:xyz@example.com">Mr Xyz</a> in a @author line.

Code Snippets

Do use @code or <code></code> tags to write code snippets. It is generally advised to use the xml tag variant since it avoids problems with { and } in the code samples. It can be useful to use the @code variant for very short inlined code samples.

Formatting

Please use <br/> and <p></p> to format your documentation. Javadoc does not understand newlines.

Exceptions

Sample

/**
 * <p>This class implements a {@link Boat}. It is designed for high speed and good maneuverability.
 * It is not designed for long term stability and you might fare better with a {@link Ferry} if
 * speed is not of prime essence.</p>
 * 
 * <p>It is advised to instantiate a Boat via a {@link BoatFactory} for maximum modularity. 
 * For example like:</p>
 * 
 * <code>
 * BoatFactory fact = new BoatFactory(HoverCraft.class);
 * Boat boat = fact.newBoat();
 * </code>
 * 
 * @seealso Ferry
 * @seealso Canoe
 * @see BoatFactory
 * @author <a href="mailto:john.doe@example.com">John Doe</a>
 */
 public class HoverCraft {...