ITEC 120 2008spring ibarland, jdymacek

home—info—exams—lectures—labs—hws
Recipe—Laws—lies—syntax—java.lang docs—java.util docs

lect02-javadoc
Javadoc

You've (hopefully) noticed in the code presented in class, the function is preceded by comments, and the comments have kinda a funny format, what with those “@” signs. The comments are in a special format, called “javadoc”. They explain what the parameters numPizzas and size mean, and what the returned answer means. They help people understand your program, without having to read the bare code.

• The javadoc comment begins with /**, which is one more asterisk than normal comments use.
• The javadoc comment is placed immediately before the function it's describing.
• The first line is a brief summary of the what the function does (which is different from how it does it!)
• The next line tells people what the parameter means: @param followed by the parameter-name followed by a brief description.
• The next line tells people what the function returns; it starts with the special word @param. (Sometimes this is identical to the first javadoc line.)
• After the @return line is an appropriate place to list your test cases.

There is a bonus to writing this information using those tags @param and @return: In BlueJ, select Tools > Project Documentation Voila! Other programmers can look at this web page for pizzaServer, and know how to call our functions, without ever actually having to look at our code!

Tip: I addition to having a javadoc comment in front of each function/method, you can put a comment at the start of your entire file, preceding the class declaration itself. You won't have “param” or “return” keywords, but instead you describe the overall class, and include your name with the “@author” tag:

/** A class to demonstrate some javadoc comments.
 *  @see http://www.radford.edu/itec120/2008spring/Lectures/lect02-javadoc.html
 *  @author Ian Barland
 *  @version 2008.Jan.26
 */
class DemoDummy {

  /** A method to square a number.
   * @param x the number to be squared.
   * @return x^2.
   *
   * Examples, if dd is an instance of DemoDummy:
   *    dd.square(  0   ) =   0
   *    dd.square(  1   ) =   1
   *    dd.square(  2   ) =   4
   *    dd.square(  1.5 ) =   2.25
   *    dd.square( 10   ) = 100.0
   */
  double square( double x ) {
    return x*x;
    }

  }

home—info—exams—lectures—labs—hws
Recipe—Laws—lies—syntax—java.lang docs—java.util docs

©2008, Ian Barland, Radford University Last modified 2008.Jan.26 (Sat)

Please mail any suggestions (incl. typos, broken links) to iba�rlandrad�ford.edu