javadoc Comments

1

• javadoc Comments

2
javadoc Comments

• Java API has a documentation tool called javadoc
• The javadoc tool is used on the source code
  embedded with javadoc-style comments
• It generates HTML based documentation of the Java
  source code automatically

3
javadoc Comments

• A javadoc comment begins with the / marker and
  ends with the / marker.
• The following is a javadoc comment
• /
• This is a ltbgtjavadoclt/bgt comment.
• /
• Because javadoc generates an HTML file, any valid
  HTML can be embedded.
• A javadoc comment may be composed of mutliple
  lines

4
javadoc Comments

• The characters are a marker we use to make the
  javadoc comments more readable in the source file
• they will not appear in the generated HTML
  documents
• blanks and tabs are also removed, so we need to
  use an HTML tag ltpgt to mark a new paragraph
• /
• This is paragraph one.
• ltpgt
• This is paragraph two.
• ltpgt
• This is the last paragraph.
• /

5
javadoc Comments

• Other notes
• The first sentence of a javadoc comment should be
  written as a summary of the comment
• For the javadoc comments to be recognized as such
  by the javadoc tool, they must appear immediately
  before the class, interface, constructor, method,
  or data member declarations.

6
javadoc Comments

• There are a number of special tags we can embed
  with the javadoc comments
• These tags start with the at symbol _at_.
• We will mention only the more common ones. For a
  complete list, refer to the Sun web site
• Javadoc tags must start at the beginning of a line

7
javadoc Comments

• _at_author
• Use this tag to create an author entry. You can
  have multiple _at_author tags.
• This tag is meaningful only for the
  class/interface javadoc comment.
• _at_version
• Use this tag to create a version entry. A javadoc
  comment may contain at most one _at_version tag
• Version normally refers to the version of the
  software

8
javadoc Comments

• _at_see
• this tag adds a hyperlinked "See Also" entry to
  the class
• Three examples
• _at_see java.lang.String
• _at_see String
• _at_see javabook.JavaBookDialog
• _at_param
• Use this tag to add a parameter description for a
  method
• This tag contains two parts the name of the
  parameter and the description of the parameter
• The decription can be more than one line
• _at_param size the length of the passed array

9
javadoc Comments

• _at_return
• Use this tag to add a return type description for
  a method
• This tag is meaningful only if the methods
  return is non-void
• Heres an example
• _at_return true if the array is empty otherwise
  return false
• There are many more online!