Documentation with Javadoc

Every field, method, class and interface should be commenting following the conventions stated below:

The Javadoc comments should be placed directly before the declaration.

NetBeans can automatically generate Javadoc comments for public methods. All tags that are suggested by default have to be used (and not only for the public methods).

  • The first line starts with "/**", so that the comment can be recognized as Javadoc.
  • The first sentence includes a short description of the method, which will be displayed subsequently when the method is employed during development. Usually the description starts with a verb using third person.
  • For every parameter a line starting the tag @param follows. If there are multiple parameters, blanks should be added after the names of the parameters, so all parameter descriptions are flush. If the short description is followed by a sentence, they need to be separated by a period.
  • In case the method returns a value the @return tag is used. The return value has to be described, even if it’s apparent from the method description. Special cases/exceptions are documented here, e.g. what the return value is if there are invalid parameter values.
  • The last line of the comment ends with "*/"
  • Example:
 /**
  * Creates a new image from the current one with overlaying text. 
  * The text may overflow, then it will not be fully displayed. 
   *
   * @param text the text to be added
  * @param x the x coordinate. Specified as pixel. 
   * @param y the y coordinate. Specified as pixel. 
  * @return a new picture with overlaying text. If the coordinates
  * are outside of the image, the text will not be visible.
   */
 public Image insertText(String text, int x, int y) {..}

 

Every class needs to have a Javadoc comment, which contains a description and afterwards a @author tag for every author.

Additional necessary comments within a class or a method should not be Javadoc comments (starting with "/**") . Instead block comments (starting with "/*") or single line comments (starting with "//") should be used, as Javadoc comments will always be associated with the proximate declaration.

 

Additional Information can be found on the Oracle website.