Think Java, 2nd Edition

Appendix B. Javadoc

Java programs have three types of comments:

End-of-line comments

These start with // and generally contain short phrases that explain specific lines of code.

Multiline comments

These start with /* and end with */, and are typically used for copyright statements.

Documentation comments

These start with /** and end with */, and describe what each class and method does.

End-of-line and multiline comments are written primarily for yourself. They help you remember specific details about your source code. Documentation comments, on the other hand, are written for others. They explain how to use your classes and methods in other programs.

A nice feature of the Java language is the ability to embed documentation in the source code itself. That way, you can write it as you go, and as things change, it is easier to keep the documentation consistent with the code.

You can extract documentation from your source code, and generate well-formatted HTML pages, using a tool called Javadoc. This tool is included with the Java compiler, and it is widely used. In fact, the official documentation for the Java library is generated by Javadoc.

Reading Documentation

As an example, let’s look at the documentation for Scanner, a class we first used in “The Scanner Class”. You can find the documentation quickly by doing a web search for “Java Scanner”. Figure B-1 shows a screenshot of the page.

Figure B-1. The documentation for Scanner

Documentation for other classes uses a similar format. The ...