Java 17 Recipes

1-12. Documenting Your Code
 Problem
You want to document some of your Java classes to assist in future maintenance.
 Solution
Use JavaDoc to place comments before any package, class, method, or field that you 
want to document. To begin such a comment, write the characters /**. Then begin each 
subsequent line with an asterisk (*). Lastly, close the comment with the characters */ on 
a line by themselves at the end. Listing 
1-10
 shows a method commented with JavaDoc.
Listing 1-10. Comments Made in JavaDoc Form
package org.java17recipes.chapter01.recipe01_12;
import java.math.BigInteger;
public class JavadocExample {
/**
* Accepts an unlimited number of values and
* returns the sum.
*
* @param nums Must be an array of BigInteger values.
* @return Sum of all numbers in the array.
*/
public static BigInteger addNumbers(BigInteger[] nums) {
BigInteger result = new BigInteger("0");
for (BigInteger num:nums){
result = result.add(num);
}
return result;
}
/**
* Test the addNumbers method.
* @param args not used
*/
ChApteR 1 GettInG StARted wIth JAvA 17

---

42
public static void main (String[] args) {
BigInteger[] someValues = {BigInteger.TEN, BigInteger.ONE};
System.out.println(addNumbers(someValues));
}
}
Comments can be added to the beginning of the package, classes, and fields in the 
same way. The comments are helpful to you and other programmers maintaining the 
code, and their specific format enables the easy generation of an HTML reference to 
your code.
Generate the HTML reference by invoking the JavaDoc tool. This command-line 
tool parses a named Java source file and formulates HTML documentation based on the 
defined class elements and JavaDoc comments. The following is an example.
javadoc JavadocExample.java
This command produces several HTML files containing the documentation for the 
package, class, methods, and fields. If no JavaDoc comments exist within the source, 
some default documentation is still produced. To view the documentation, load the 
following file into your browser.
index.html
The file is in the same directory as the class or package you are documenting. There 
is also an index-all.html file giving a strict alphabetical listing of documented entities.
Keep in mind that the same rules apply when using the JavaDoc tool as when using 
javac. You must reside within the same directory as the source file or prepend the file’s 
name with the path to where the file is located.
The output is shown in Figure 
1-17
.
ChApteR 1 GettInG StARted wIth JAvA 17

---

43