Javadoc Guidelines

Basic Tags:

<br> carriage return, when writing html carriage returns in the file are ignored.
  any amount of white space is treated as one space, so this tag is needed for forcing more spaces
> > this is a special character in html, so you need to escape it somehow
< < this is a special character in html, so you need to escape it somehow
<p> text </p> mark a paragraph
<b> text </b> boldface text
<em> text </em> emphasis
<i> text </i> italics
<h1> text </h1> top level header, h2 and h3 are lower level headers
<a href="link"> link text </a> add a hyper link.
<ul>
<li> list item </li>
...
</ul>
This adds a list to the documentation.

Hyper links

To link to an external site, the link should be something like http://foo.com/some_file.html. To do links to some html file in the source tree the link should be "doc-files/foo.html" where foo.html is the html file you want to link to. This file needs to live in doc-files, for the package begin documented, otherwise javadoc won't copy it over. This isn't limited to html files though, images and other documents can be linked to as well. Although it is preferred that the links be gif, jpg, html, png, txt only. That way all browsers can view them. Word and Excel are common Windows formats so they can be included, but it'd be better to use the save as html feature of the Office applications to save out an html version of the document and just link to that instead.

Images

Images can be added as well. Use:
<img src="doc-files/foo.gif">
to link to the image, foo.gif. This will put the picture inline in the document.

Javadoc specifics

Javadoc comments are text inside /** and **/. Comments must be directly above the class, method or variable being documented. Up to the first period is considered the short description for the class, package or method being documented. Don't put images, lists or other large tags in here, they will generally be filtered out and will make the formatting of the document rather messy.

Javadoc has it's own tags that extend the regular html tags. Here are some useful ones:

@see foo.bar adds a see also link to package foo.bar
@see foo#bar(Object, int) adds a link to the method bar in class foo that has the signature Object, int. The class name needs to be fully qualified unless it is in the regular scope of the code, ie. if it needs a fully qualified name to be inserted as real code there, it needs it in the documentation. The signature may be ommitted if there is only one method with that name. The class name may be omitted if the method is in the same class that is being documented. The method name and signature may be omitted to just link to the documentation for the class.
{@link class#method(signature)} may be used for inline links. The same rules apply as for @see links. The only difference is that the link is inline, otherwise the link ends up down in the See also list.
@param name descrption describes the parameter name on a method
@return description describes the return value of a method
@version text gives the version of a class or package as text
@pre (conditional) denotes a precondition that will show up in the list of preconditions, if preprocessed with an assertion package code is generated from this.
@post (conditional) denotes a postcondition that will show up in the list of preconditions, if preprocessed with an assertion package code is generated from this.
@invariant (conditional) denotes an invariant, if preprocessed with an assertion package code is generated from this. This is only useful on a class and must occur inside the {} that define the class

All tags can be nested, at least from my experience. More documentation can be found here.

Commenting package

For package level documentation, add a file called package.html in the same directory as the code for the package and put your documentation there. Javadoc will find it. Here is a template for the file:

<html>
	<body>
	  This is my short description.
	  Here's some large description of the package with images and
	  links.
	</body>
</html>

Remember to add the html and body tags, otherwise javadoc will ignore the file. Note that all references to other documentation in package.html files must be fully qualified

Last modified: Mon Mar 22 17:29:08 CST 2004