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 ...
Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month, and much more.
