Google
 

 

up previous next contents
Up: 2. Day 2: The Previous: 2.5 Strings Next: 2.7 Flow control and   Contents

Subsections

2.6 Comments and Javadoc

2.6.1 Types of comments

  • Three different ways to put comments in your Java code:

// define a comment to the end of the current row
/* ... */ define a multi-line comment between the two symbols
/** ...*/ a "Javadoc" multi-line comment

2.6.2 Javadoc comment tags

  • The following special tags in Javadoc comments have predefined purposes.

2.6.2.1 @see

  • Creates a link to other javadoc documentation.
  • Name any identifier, but qualify it sufficiently. 
      @see Attr
  @see COM.missiondata.web.utils.PageFactory;

2.6.2.2 @param

  • Documents a single parameter to a method.
  • Have one for each parameter of the method.
  • First word is the parameter name, the rest is its description. 
      @param max The maximum number of words to read.

2.6.2.3 @return

  • Documents the return value of a method: 
      @return The number of words actually read.

2.6.2.4 @exception

  • Documents an exception thrown by the method.
  • Should have one for each type of exception the method throws. 
      @exception UnknownName The name is unknown.
  @exception IllegalArgumentException
  The name is <code>null</code>.

2.6.2.5 @deprecated

  • Marks an identifier as being unfit for continued use.
  • Code using a deprecated type, constructor, method or field will generate a warning when compiled. 
       \begin{enumerate}
   \item 
   \item @deprecated Do not use this anymore.
   \item 
   \end{enumerate}

2.6.2.6 @author

  • Specify the author of the code. 
      @author Alvin Alexander

2.6.2.7 @version

  • Specify an arbitrary version. 
      @version 1.11

2.6.2.8 @since

  • Specify an arbitrary version specification that denotes when the tagged entity was added to your system 
      @since 2.1

2.6.3 A comment example

  • A heavily-commented Attr class: 
      class Attr
  {
      \begin{enumerate}
      \item  The attribute name. */
      \end{enumerate}
   \end{enumerate}
     private String name;

      \begin{enumerate}
      \item  The attribute value. */
      \end{enumerate}
   \end{enumerate}
     private Object value = null;

    /**
     * Creates a new attribute.
     * @see Attr2
     */
     public Attr (String name)
     {
        this.name = name;
     }
  }

2.6.4 Notes on Usage

  • Use the javadoc command to print a separate set of HTML javadoc pages for your classes.
  • See http://java.sun.com/j2se/1.4/docs/api/ for an example of javadoc documentation pages for the Java2 Platform.
  • Comment skew - comments become out of date as the source code changes over time.
  • Some programmers write documentation, others do not.
  • Some businesses have technical writers that end up needing write access to your Java source code files.