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.