Chapter 3

Doc comments

What are the limitations of conventional comments in source code? What information is present in the code itself, which would be useful for documentation? What things would you like to see documented in an API?

• Two types of comments in Java source code:
  1. Standard comments that are readable only within the source:

  // A single line comment is terminated by a newline
  
  /* Comment that has special start and end markers */
  
  /* 
   * These comments can extend
   * to multiple lines
   */
        

  2. Special doc comments that can easily be converted into an HTML page
  • /** */ marks the start and end of a special doc comment
  • The javadoc program generates API documentation from the doc comments in source code.

  /**
   * This comment will get converted to HTML 
   * by the <b>javadoc</b> tool
   */
  
  /**
   * An example class comment
   *
   * @author John Lowry
   * @see java.awt.Button
   */
  class MyButton extends Button {
  
  }
        

Examples of special tags recognized by javadoc

Tag	Applies to	What it does	Usage example
@see classname	class, interface, method	Adds a hyperlinked See Also entry	@see java.lang.String
@deprecated text	class, interface, method	Adds a comment that this API should not longer be used	@deprecated Replaced by setBounds(int, int, int)
@param name description	method	Documents a parameter	@param index The index of the desired character
@return description	method	Adds a description of the return value	@return The desired character

Exercise Look at the javadoc home page. What other tags are available besides those listed above?

Review

• What is a doc comment?

---

[ Chapter contents ] [ Course contents ] [   ] [ Home ] [ Curriculum ]

http://www.keller.com/java/chapter_3/doc/comments.html
Updated Wednesday, 31-Oct-2001 14:19:06 CST

Copyright © 2001

Dan Keller Technical Services 4500 19th St., San Francisco California, USA 94114 tel: 415 / 861-4500