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.