JavaDoc

Agenda

• What is Javadoc?
• Writing Javadoc comments
• Using the Javadoc tool

What is Javadoc?

• Javadoc is a tool for generating documentation for java code.
• Javadoc comments are used to document classes, methods, and fields in java code.
• Javadoc tool can be run to generate documentation in HTML format.

Why use Javadoc?

• It's much faster than generating webpages documenting your code.
• It's standard documentation which means it's easy to use and the structure is given.

Writing Javadoc Comment

• Javadoc comments start with /** and end with */
• The placement of the comment is important.
• The following can be commented:
• classes
• methods
• instance variables
• static variables

Commenting a Class

• Put the comment immediately before the class declaration.
• Briefly describe the purpose of the class in 2-3 sentences.
• Optionally include
• @author tag
• @version tag
• others

Writing Javadoc Comment

package diceGame;

/**

* This class creates dice object.

* This class can create dices of different sizes.

* Users can roll the dice.

*

* @version 1.0

* @author CSCI 2121 Instructor

*/

public class Die

{

/** constructor to create dice object */

public Die();

}

Javadoc

Comments

Commenting a Method

• Put the comment immediately before the method declaration.
• Briefly describe the purpose of the method in a short phrase or 2-3 sentences. Include more detail if necessary
• Include these tags if needed
• @param name – describes parameter
• @return – describes the return value

Commenting Instance and Static Variables

• Put the comment immediately before the variable declaration.
• Briefly describe the purpose of the variable in a short phrase. Include more detail only if absolutely necessary.
• No tags needed.

For more information...

Visit the article:

How to Write Doc Comments for the Javadoc Tool

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html