The javadoc utility formats documentation comments into a neat set of documents that you can view in a web browser. It makes good use of the seemingly repetitive phrases. The first sentence of each method comment is used for a summary table of all methods of your class (see Figure 9.4.1).
Figure 9.4.1: A Method Summary Generated by javadoc.
The @param and @return comments are neatly formatted in the detail description of each method (see Figure 9.4.2). If you omit any of the comments, then javadoc generates documents that look strangely empty.
Figure 9.4.2: Method Detail Generated by javadoc.
This documentation format may look familiar. It is the same format that is used in the official Java documentation. The programmers who implement the Java library use javadoc themselves. They too document every class, every method, every parameter, and every return value, and then use javadoc to extract the documentation.
Many integrated programming environments can execute javadoc for you. Alternatively, you can invoke the javadoc utility from a shell window, by issuing the command
javadoc MyClass.java
The javadoc utility produces files such as MyClass.html in HTML format, which you can inspect in a browser. You can use hyperlinks to navigate to other classes and methods.
You can run javadoc before implementing any methods. Just leave all the method bodies empty. Don’t run the compiler—it would complain about missing return values. Simply run javadoc on your file to generate the documentation for the public interface that you are about to implement.
The javadoc tool is wonderful because it does one thing right: It allows you to put the documentation together with your code. That way, when you update your programs, you can see right away which documentation needs to be updated. Hopefully, you will update it right then and there. Afterward, run javadoc again and get updated information that is timely and nicely formatted.
If you like my code then follow me on my social media. Thank you!
