Documentation Commentsand

JavaDoc

• Single-Line Comments:

– These are what we have been using and will continue to use.

– Ex: // The compiler ignores everything after the double

// slashes. These are single line comments.

• Documentation Comments:– These are comments that can be read and processed

by a program named “javadoc,” which comes with the Java SDK.

• JavaDoc:– Creates formatted HTML files that document the

source code.– If there are documentation comments in the source

code, JavaDoc knows to put them in the HTML files!

• To add documentation comments:– Use a forward slash and two stars to start:

/**

– Use a star and a forward slash to end:*/

– Ex:

/**

* This is an example of a documentation comment.

*/

• Use documentation comments before:

– Class Headers to describe what the class does.

– Method Headers to describe what the method does.

– Ex:

/*** This class calculates the area of a Rectangle.*/public class Rectangle{……}

• You can also add documentation comments about a method’s parameters and its return value:

• Use the following format for parameters:@param parameterName Description

Ex: @param intPNum1 This is the first number to be added.

• Use the following format for return values:@return Description

Ex: @return This returns the sum of two numbers.

• Ex:

/***The sumNumbers method returns the sum of two numbers.*@param intPNum1 This is the first number to be added.*@param intPNum2 This is the second number to be added.*@return This returns the total of intPNum1 and intPNum2.*public static int sumNumbers(int intPNum1, int intPNum2){ int intTotal;

intTotal = intPNum1+ intPNum2;

return intTotal;}

• To run javadoc, you can do it from the command prompt on a source file:Ex: javadoc Rectangle.java

• To run javadoc on a project with multiple classes:– Right-click on the project name in Netbeans.– Select “Generate Javadoc.”– The JavaDoc will be created in the “dist”

folder of the java project.