CPE102 - How to write simple Java documentation for the javadoc tool

The javadoc-style of comments allows a utility that comes with the Java development environment (called javadoc) to read your source code and generate html files documenting your class.  It is very easy to write the comments and use the utility to generate very readable and useful documentation for classes you write. We will be using a subset of the supported features, if you would like to learn more about writing javadocs see the how-to documentation provided by Oracle.

You will be documenting the public methods in some of the Java files you write this quarter.  In a typical development effort you would document all of the public methods in all of the source files but, since this is a learning environment and in the interest of reducing your workload, I will only require you to document some of your code - hopefully enough to ensure that you know how to use the tool!

To document a method you must include a comment block immediately preceeding the method you are documenting similar to this one (note that the items in bold are bold to draw your attention to them, not necessary (or possible) to bold in your source file):

1   /**
2    * A sentence (must be terminated with a period, '.') describing at a high level what
3    * this method does.  The first sentence will be part of the brief description that is
4    * generated by the javadoc tool. Any additional text will be part of the detailed
5    * description.
6    *
7    * @param someValue A description of what this parameter is for.  Should include 
8    * restriction, if any, on the values passed in.
9    *
10   * @param anotherValue A description of what this parameter is for.  Should include 
11   * restriction, if any, on the values passed in.
12   *
13   * @return A description of what value(s) are returned and under what specific
14   * circumstances.
15   *
16   * @throws InvalidArgumentException describe when this exception is thrown by the
17   * method.

18   */
19   public double someMethod(String someValue, int anotherValue)
20   {
21      // Code for method not shown
22   }

Let's examine the example above in detail:
When you have completed documenting the class you are ready to generate the HTML files using the javadoc utility included with the JDK (Java Development Kit).  See How to Generate JavaDoc HTML Files for instructions on how to proceed.