Difference between revisions of "Documenting source code using Javadoc"

From Knowledge Kitchen
Jump to navigation Jump to search
m (More)
m (Fields)
 
Line 44: Line 44:
 
==Fields==
 
==Fields==
 
'''Required documentation'''
 
'''Required documentation'''
*a layman's description of the purpose of the field
+
None.  You are not required to leave javadoc comments for fields.
 +
 
 +
However, if you feel like it would add clarity and readability to your code, you can write a javadoc comment with a layman's description of the purpose of the field.
  
 
'''Example:'''
 
'''Example:'''

Latest revision as of 08:01, 12 September 2019


All programming assignments must include javadoc comments in the source code

Javadoc is a tool built into the Java Development Kit that automatically generates documentation of your source code. The javadoc tool depends upon you adding special comments into your code that include the necessary documentation. In order to use it effectively, you must add javadoc comments for all class definitions, method definitions.

The javadoc tool is run from Eclipse by clicking Project->Generate javadoc. This generates documentation in a folder named doc within your project folder. You can open this documentation in your web browser.

Class definitions

Required documentation:

  • a short layman's description of the class
  • an @author tag for each author
  • a @version tag

Example:

/**
 * Program to output the message, "Hello world".
 *
 * @author Foo Barstein
 * @version 0.1 
 */
public class HelloWorld { ... }

Method definitions

Required documentation:

  • a short layman's description of the purpose of the method
  • a @param tag for each parameter for the method
  • a @return tag if the method returns a value (not necessary for void methods)
  • an @exception tag for each exception thrown by the method

Example:

/**
 * Outputs "Hello world" to the console.
 * @param args String array of any arguments supplied when running the program.
 * @return void main functions must not have any return value, since they are declared as void
 */
public static void main(String[] args) { ... }

Fields

Required documentation None. You are not required to leave javadoc comments for fields.

However, if you feel like it would add clarity and readability to your code, you can write a javadoc comment with a layman's description of the purpose of the field.

Example:

/**
 * A flag to show whether breakfast has been eaten.
 */
public boolean isEaten = false ;

More

The documentation outlined here is the bare minimum of what javadoc offers. Here is a more complete reference list adapted from David Flanagan, Java in a Nutshell, Second Edition, (O’Reilly 1997), including javadoc tags that are not required in this course:

@author text

  • Adds an “Author:” entry containing the specified text.
  • Used to document class definitions

@param parameter-name description

  • Adds the specified parameter and its specified description to the “Parameters:” section of the current method. If the description is longer than one line, it may be continued on the next.
  • Used to document method definitions

@return description

  • Adds a “Returns:” section containing the specified description to the documentation.
  • Used to document method definitions

@exception full-classname description

  • Adds a “Throws:” entry to the documentation. The entry contains the specified class name of the exception, and the description specified, which should explain the significance of the exception.
  • Used to document method definitions

@see classname

  • Adds a “See Also:” entry to the documentation that contains a hyperlink to the specified class (or interface).
  • Used to document class, method, and field definitions

@see full-classname Type, Method, Field

  • Adds a “See Also:” entry to the documentation that contains a hyperlink to the specified class (or interface).
  • Used to document class, method, and field definitions

@see full-classname#method-name Type, Method, Field

  • Adds a “See Also:” entry to the documentation that contains a hyperlink to the specified method of the specified class (or interface).
  • Used to document class, method, and field definitions


What links here