Javadoc Quick Startup Information
This information was sent by e-mail from Roberto Passerone on 9 July 1999.
Javadoc is used to create the documentation for a program. It extracts the information
from the comments in the source code. The documentation is generated in HTML format, but
other formats will be possible in the near future.
To start a javadoc comment, use the /** string. Example:
/**
*
* Hi, this is a javadoc comment
*
*/
The closing of the comment is the same as the usual one. Comments starting with // are not
valid. The documentation for a class must be inserted right before the class
declaration. The documentation for an attribute or method must be inserted right before
the corresponding declaration. In the comments you can use any HTML command. There
are also special tags that are used to identify a specific piece of information. To
comment a class, here is an example of class goofy.
/**
*
* This class represents a funny dog. It extends class "pet", from
* which it inherits the method "eat_a_lot".
*
* @author Walt Disney
* @version 1.0 (here you could use the cvs macro expansion mechanism)
*
*/
class goofy extends pet {
...
}
Here @author and @version are an example of two tags. In the case of methods, you also
have tags to identify the parameters:
/**
*
* This function emits a barking sound.
*
* @param duration The duration, in milliseconds, of the sound to be
* produced
* @return True if the sound card was found, false otherwise
*
*/
public boolean bark( int duration ) {
...
return true;
}
The tag @see can be used to reference other methods in the same or different class (it is
displayed as a link in the documentation).
To generate the documentation simply run javadoc on the desired files. By default,
javadoc only documents public classes and methods. To get the documentation for all
classes and methods, use the -private switch. After running the program, you'll see
a bunch of .html files, which depending on the version you are using, contain indexes,
frames, etc.
These are the basics. The documentation which comes with the JDK explains everything in
quite some details.
|
