How to Create Javadoc When Commenting

Introduction

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.

Instructions

Steps

Step One

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.<code>""/**<br /> * 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.<br />

*/""</code>

Step Two

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.

Step Three

Use the method description. This meta-tag has no tag name: It's simply the comment that comes

before the other tags.<code>""/**<br /> * Computes the slope of a line.<br /> */""</code>

Step Four

Incorporate parameter descriptions. These are denoted by the @param meta-tags, which should

be followed by a parameter name and description.<code>""/**<br /> * Computes the slope of a

line.<br /> *<br /> * @param p1 First point that describes the line<br /> * @param p2 Second

point that describes the line<br /> */""</code>

Step Five

Return value descriptions. This is denoted by the @return meta-tag and should be followed by a

description of the return value.<code>""/**<br /> * Computes the slope of a line.<br /> *<br />

* @param p1 First point that describes the line<br /> * @param p2 Second point that describes

the line<br /> * @return Slope of the line as a float<br /> */""</code>

Step Six

Add attribution tags. The tags attribute the code to a specific author.<code>""/**<br /> *

Computes the slope of a line.<br /> *<br /> * @Author Jack Smith<br /> * @param p1 First

point that describes the line<br /> * @param p2 Second point that describes the line<br /> *

@return Slope of the line as a float<br /> */""</code>

Step Seven

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).<code>""javadoc -d docs *.java""</code><br />