Documentation Comments and JavaDoc

1. Documentation Commentsand JavaDoc

2. 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.

3. 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!

4. 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. */

5. 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 { …… }

6. 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.

7. 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; }

8. 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.