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. Special characters like ', ", and so on, should be written in the javadoc source as ', ", not as their corresponding html entity references, like ". Then only exception is < and >, which must be written as < and >

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 {...