Download Javadoc quick guide

Javadoc quick guide
Doc comments begin with /** and end with */. They can appear immediately
before a class, field (public class or instance variable), constructor or method
definition. Inside the doc comment, the first part is the description, followed by
zero or more tags which begin @. Common standard tags are:
@author (doesn’t show up in HTML)
@deprecated mumble...
@see ”whatever”
@see <a href=”some url”>label</a>
@see #field (in current class)
@see #method (in current class)
@see #method(int, String)
@see class#method(int, String)
@see package.class#method(int, String), etc.
For methods, these tags are also available:
@param parameter-name description
@return description (return type and range of values)
@throws exception-class description
(There is a tag @version which could be used for classes, but our CVS version
numbers often do not mean a lot.)
Apart from the tags and stripping of leading * from lines, doc comments are
written in HTML. But the way to create links to other bits of Javadoc is by
putting something like {@link package.class#method label} in the middle of the
text. <a> should be used only for ‘external’ links. Method descriptions should
use the third person—‘gets the current handler’ rather than ‘get the current
handler’—and the first word should be the verb.
More information
Based on Sun’s longer document at http://java.sun.com/j2se/1.3/docs/
tooldocs/solaris/javadoc.html, which also describes ‘overview’ documentation for whole packages or libraries, and on their style guide at http://java.
sun.com/j2se/javadoc/writingdoccomments/index.html. The aD coding
standards have a short section on comments at http://developer.arsdigita.
com/acs-java/engineering-standards/comments.html.
Examples
/**
* Listens for PieRequest messages and responds with Apple or Custard
* as appropriate. For example:
* <code><pre>
*
Listener pl = new PieListener(kitchen);
*
int n = pl.forty();
* </pre></code>
*
* @author Bunty Hoven
*/
public class PieListener {
/** The z-coordinate of the component. */
public int z = 0;
/**
* Makes a new PieListener with the default frobnication level.
*
* @param name a String of "title surname"
*/
public PieListener(String name) {
System.err.println("Here we go again");
}
/**
* Prints a greeting - {@link #forty link to the method ’forty’}.
*/
public static void sayHello(String[] args) {
System.out.println("Hello, world");
}
/**
* Returns a useful number which you may use for any purpose
* without fee. Other integers are available as part of our
* licensed product.
*
* @author Ed Avis ([email protected])
* @return int the number 40
* @see "The Java Programming Language"
* @see <a href="http://slashdot.org/">goatse.cx</a>
* @see #sayHello
* @deprecated As of 4.1, the preferred way to get the number 40
* is the {@link FortyFactory#next FortyFactory.next} method.
*/
public int forty() { return 40; }
}