Java Notes

Javadoc

Javadoc is a utility that extracts documentation from source files and produces HTML documentation files.

How to write Javadoc comments

Javadoc comments consist of text/HTML and special tags enclosed between /** and */ immediately preceding the element they describe.

[TODO]

Running Javadoc for simple programs

The easiest way to use javadoc is to use it from Ant.

Alternatively, you can do it from the command line. If you have one or more .java files in a directory and haven't explicitly defined a package, use the following command to generate documenation in the sub directory docs, which javadoc creates if it doesn't exist. This command is run from the directory containing the source files. Class files in the same directory cause no problems. javadoc produces quite a number of files -- about 13 files plus one per class. Click on docs/index.html to see the documentation. This produces documentation on all private, protected, package, and public classes and their members (constructors, methods, fields).

javadoc -d docs -private -source 1.4 *.java

The parameters have the following meaning.

• -d docs - Put the HTML files in a docs subdirectory of the current directory.
• [an error occurred while processing this directive] -private - Create descriptions of all private, protected, package and public elements.
• -source 1.4 - Allow language features up thru v 1.4 (eg, assert).
• *.java - Process all Java source files in the current directory.

Tags

Tags are special values specified with an at-sign, and followed by a value.

Common class documentation tags

• @author
• @version

Common constructor and method tags

• @param
• @return
• @throws