Difference between revisions of "Documenting source code using Javadoc"

From Knowledge Kitchen
Jump to navigation Jump to search
m (Fields)
m (Method definitions)
 
(One intermediate revision by the same user not shown)
Line 4: Line 4:
 
'''All programming assignments must include javadoc comments in the source code'''
 
'''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.
+
Javadoc is a tool built into the Java Development Kit that automatically generates documentation of your source code based on comments written in a particular syntax, and allows development environments, such as Eclipse, to offer intelligent tooltips that show this documentation when using methods or classes commented in such a manner.  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.
 
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.
Line 35: Line 35:
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
 
/**
 
/**
  * Outputs "Hello world" to the console.
+
  * Calculate the sum of two numbers
  * @param args String array of any arguments supplied when running the program.
+
* @param num1 The first number, as an integer.
  * @return void main functions must not have any return value, since they are declared as void
+
  * @param num2 The second number to add to the first
 +
  * @return The sum of the two integers
 
  */
 
  */
public static void main(String[] args) { ... }
+
public static void sum(int num1, int num2) { ... }
 
</syntaxhighlight>
 
</syntaxhighlight>
  

Latest revision as of 14:05, 1 December 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 based on comments written in a particular syntax, and allows development environments, such as Eclipse, to offer intelligent tooltips that show this documentation when using methods or classes commented in such a manner. 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:

/**
 * Calculate the sum of two numbers
 * @param num1 The first number, as an integer.
 * @param num2 The second number to add to the first
 * @return The sum of the two integers
 */
public static void sum(int num1, int num2) { ... }

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