How to Create Javadoc When Commenting

Javadoc is the de facto standard for generating documentation from source code. It's a tool to create HTML documentation from specially formatted comments in Java code. This can be used to generate structured application programming interface (API) documentation automatically, give some hints to the IDE or for attribution of packages, classes and methods. Essentially, it's a way of commenting on parameter descriptions, who wrote what, and who to blame if it breaks. Java comes with the javadoc command-line program to generate the HTML documentation, but most Java integrated development environments (IDEs) also have this integrated.

Difficulty: Moderate

Instructions

1. Create special javadoc comments. To denote a javadoc comment, start the comment with /**. Javadoc comments usually exist at the top of a file, before classes and before methods. Since it's designed for full API documentation, it's not uncommon to see files with more javadoc comments than code.""/**
* This is a javadoc comment. It doesn't have any javadoc meta-tags yet, but it did trigger the javadoc parser to take a look at this comment.
*/""

2. Add API meta-tags (tags that describe the API itself) when commenting. API tags are parameter names, descriptions, exception profiles, return value descriptions, method names and method descriptions. Many IDEs incorporate this data into their tool tips and other helpers, as well as it being for use in HTML or comment form.

3. Use the method description. This meta-tag has no tag name: It's simply the comment that comes before the other tags.""/**
* Computes the slope of a line.
*/""

4. Incorporate parameter descriptions. These are denoted by the @param meta-tags, which should be followed by a parameter name and description.""/**
* Computes the slope of a line.
*
* @param p1 First point that describes the line
* @param p2 Second point that describes the line
*/""

5. Return value descriptions. This is denoted by the @return meta-tag and should be followed by a description of the return value.""/**
* Computes the slope of a line.
*
* @param p1 First point that describes the line
* @param p2 Second point that describes the line
* @return Slope of the line as a float
*/""

6. Add attribution tags. The tags attribute the code to a specific author.""/**
* Computes the slope of a line.
*
* @Author Jack Smith
* @param p1 First point that describes the line
* @param p2 Second point that describes the line
* @return Slope of the line as a float
*/""

7. Generate the HTML documentation. If you're not using an IDE or you just want to do it manually, you can run the javadoc command-line program from your project directory. Specify the output directory with the -d switch and pass it a list of .java files (usually as a wildcard).""javadoc -d docs *.java""
   

Tips & Warnings

• When you're using an IDE, HTML documentation is probably done automatically as part of the build process. Refer to your IDE documentation to confirm this.
• Multi-line comments in Java traditionally start with /
• , but the extra asterisk character in Javadoc signals the javadoc parser to start looking for javadoc meta-tags.