Javadoc Guidelines

General Rules

Sun documentation



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


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

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


<body bgcolor="white">
    The first line should be a one sentence summary starting with a verb.
    Used in package overviews like :
Provides tools to build and digest Pies.

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

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:


To integrate pies in your own code start by defining a factory
Blah di blah...

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

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


{@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=""></a> syntax directly in the javadoc as well as in @see/@seealso and <a href="">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.


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 &quot;. Then only exception is < and >, which must be written as &lt; and &gt;



 * <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="">John Doe</a>
 public class HoverCraft {...

Javadoc Guidelines (last edited 2010-03-17 13:13:45 by localhost)