This quick lesson covers Javadoc, a helpful tool for generating documentation from your Java source files. This lesson is part of an ongoing series of tutorials for developers learning Java in order to develop Android applications.
Javadoc is a utility provided with the Java SDK that allows developers to generate code documentation from Java source files. Development environments like Eclipse have built-in support for Javadoc and can generate searchable HTML reference materials from Javadoc-style comments. In fact, the Android SDK reference is a form of Javadoc documentation.
Javadoc documentation uses a combination of processing the source code (and inspecting types, parameters, etc.) and reading special comment tags that the developer provides as metadata associated with a section of code.
A Javadoc-style comment must come just before the code it is associated with. For example, a Javadoc comment for a class should be just above the class declaration and a comment for a method should be just above the method declaration. Each comment should begin with a short description, followed by an option longer description. Then you can include an number of different metadata tags, which must be supplied in a specific order. Some important tags include:
You can also create your own custom tags for use in documentation.
While you are writing code in Eclipse, you can generate a Javadoc –style comment by selecting the item you want to comment (a class name, method name, etc.) and pressing Alt-Shift-J (Cmd-Shift-J on a Mac). This will create a basic Javadoc-style comment for you to fill in the details.
Let’s look at an example. Here’s a simple Javadoc comment that describes a class:
