= 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. {{{ Provides tools to build and digest Pies.

Purpose

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.

Implementation

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:

Examples

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

Related Documentation

The primary reference on pie theory is E. Idles famous article "The Pie and I" found below. }}} === 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 {{{example.com}}} syntax directly in the javadoc as well as in {{{@see}}}/{{{@seealso}}} and {{{Mr Xyz}}} in a {{{@author}}} line. === Code Snippets === Do use {{{@code}}} or {{{}}} 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 {{{
}}} and {{{

}}} 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 = {{{ /** *

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.

* *

It is advised to instantiate a Boat via a {@link BoatFactory} for maximum modularity. * For example like:

* * * BoatFactory fact = new BoatFactory(HoverCraft.class); * Boat boat = fact.newBoat(); * * * @seealso Ferry * @seealso Canoe * @see BoatFactory * @author John Doe */ public class HoverCraft {... }}}