IC211 Source Code Documentation Requirements

Rules:

Comments are required for all classes (and interfaces), public methods, and public constructors.
Comments must conform to the Javadoc standard.

Comment blocks open with /** and close with */. For example:

/**
This is a Javadoc comment block for whatever immediately follows.
*/

/**
 * You will find some examples with a * at the beginning of each line.
 * These *s are optional and not required.
 */

Your comments must be complete English sentences with proper spelling, grammar, and punctuation. The comments must contain a basic description of the class (or interface), method, or constructor and must include sufficient detail to inform the reader of:
- What the class (or interface) represents and/or the purpose for its existence.
- What happens within the method or constructor.
The comment block for the class (or interface) must be below any/all import statements.
Comments are interpreted as HTML, so you may optionally include HTML formatting if it helps to communicate with the reader.
Here are some tips/hints for using HTML in Javadoc:
- You must use <, >, and &, for <, >, and &, respectively (and other similar items).
- Other HTML tags work too. For example: <a> for hyperlinks, <em> for italics/emphasis, <strong> for bold/strong, and <u> for underlined.
- You can also make Lists and Table if you like.
- Do not use heading tags.
Following the basic comment requirement described above, you are also required to use the following four @ tags when applicable.
- @author — Only applies to the class (or interface) comment. Must be at the bottom of the comment block and in the following format:
  @author LastName, FirstName For example:
```
import java.util.*;

/**
This sentence should describe the purpose of the Foo class.
@author Gish, Joe
*/
public class Foo{
...
}
```
- @param — Applicable for all public constructors and methods that accept parameters as input. An @param tag is required for each parameter (even when the description is obvious), formatted as follows:
  @param parameterName description of parameter
- @return — Required for all public methods that do not return void, even if it is redundant with the method description. (Whenever possible, find something non-redundant (ideally, more specific) to use for the tag comment), formatted as follows:
  @return description of the item returned
- @throws — Required for all public methods whose prototypes end in throws TypeOfThrowable, formatted as follows:
  @throws TypeOfThrowable condition that causes it

Making your own Javadoc:

To generate the Javadoc from your source code, navigate to the directory where your source code is kept and do the following:

javadoc -d doc -Xdoclint:all -link https://docs.oracle.com/en/java/javase/11/docs/api *.java

The -d option creates a directory named doc with the generated HTML files.

The -Xdoclint:all option ensures that javadoc errors and warnings are output to the user.

The -link option creates hyperlinks in the generated HTML files to the Java API documentation.

Javadoc Examples

If you need inspiration or examples for what to say in your comments, you are encouraged to look up the Javadoc for any of the standard Java classes that we’ve been using all semester.

For example, see the link to the String class: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html

IC211 Source Code Documentation Requirements

Rules:

Making your own Javadoc:

Javadoc Examples

Other Helpful links

Javadoc 5.0 Tool homepage

Javadoc Tool Reference Pages

Javadoc style guide