JavaDoc
- All methods, fields and classes must have its corresponding
javadoc
. Some exceptions in the methods apply:- Getter / setter methods.
- Trivial constructor, specially no-args constructor.
- Trivial toString method.
- Trivial hashCode method.
- The methods that override other methods must inherit the
javadoc
from the overridden methods.
There are certain convention that must be followed in order to produce good javadoc
documentations:
- Each line above is indented to align with the code below the comment.
- The first line contains the begin-comment delimiter ( /**).
- Starting with Javadoc 1.4, the leading asterisks are optional.
- Write the first sentence as a short summary of the method, as Javadoc automatically places it in the method summary table (and index).
- Notice the inline tag {@link URL}, which converts to an HTML hyperlink pointing to the documentation for the URL class. This inline tag can be used anywhere that a comment can be written, such as in the text following block tags.
- If you have more than one paragraph in the doc comment, separate the paragraphs with a <p> paragraph tag, as shown.
- Insert a blank comment line between the description and the list of tags, as shown.
- The first line that begins with an “@” character ends the description. There is only one description block per doc comment; you cannot continue the description following block tags.
- The last line contains the end-comment delimiter ( */) Note that unlike the begin-comment delimiter, the end-comment contains only a single asterisk.