Javadoc is a tool for generating API documentation in HTML format from doc comments in source code. The purpose of the API is to provide information about code so other programmers can use it without needing a thorough knowledge of its inner workings. In order to produce the API, Javadoc requires comments in a particular format. The official rules for commenting are listed in a 17 page document online, so we will only be requiring a subset of this format, though it is encouraged that you read and employ the full documentation format.
/** and end with */. This can be omitted for functions
where the function name describes completely the function, such as toString. The comment
block's first line is a description of the class/interface/method followed with (in the case of
functions) any applicable tags.
@param, @return, and
@throws. A description of each tag is shown below:
@param -- The @param tag is followed by the name (not data type) of the
parameter, followed by a description of the parameter. Multiple @param tags should be
listed in argumentative order.@return -- Omit @return for methods that return void and for constructors;
include it for all other methods, even if its content is entirely redundant with the method description.
Having an explicit @return tag makes it easier for someone to find the return value
quickly. Whenever possible, supply return values for special cases (such as specifying the value
returned when an out-of-bounds argument is supplied).@throws -- A @throws tag should be included for any checked exceptions
(declared in the throws clause), and also for any unchecked exceptions that the caller might reasonably
want to catch, with the exception of NullPointerException. Errors should not be documented
as they are unpredictable.Javadoc is included in Java 2 SDK and does not need a separate download or installation.
Javadoc was created to provide information of source code to multiple programmers. For any major project involving multiple programmers, code is usually written with packages, classes, interfaces and methods. As such, Javadoc can only be applied to packages, classes and interfaces inside those packages, and methods inside of those (although exceptions are possible, they require some extra work).
When running Javadoc, run it from the command line with the following arguments:
javadoc -sourcepath code-path -d destination package-names
A description of each of the command line options is below:
-sourcepath code-path -- Specifies the classpath Javadoc will use when searching
for files.
-d destination -- Specifies where Javadoc should place the HTML files it creates.
For instance, if you wanted Javadoc to generate HTML files for a package AST, whose source files are located
in C:\cs212\AST, and output the files to C:\cs212\out, your command line arguments
would be as follows:
javadoc -sourcepath C:\cs212 -d C:\cs212\out AST
Running Javadoc produces a number of files. The starting point you want to open first is called narf. The API it produced can be viewed here.