Javadoc

Why is documentation important

One of the goals of CS2030 is to steer you away from the mindset that you are writing code that nobody else will read except you (e.g., in CS1010 labs). In order to work effectively in a software engineering team, one aspect is to document your code in accordance to a standard.

javadoc is a tool used to document Java code. It automatically generates HTML documentation from the comments in your code. The Java 17 SE API that you have seen are generated from javadoc.

How to comment for javadoc

javadoc distinguishes between normal comments and comments meant for javadoc by how we "fence" the comments. A javadoc comments always starts with /** (note the double asterisks) and ends with */ and are always placed immediately before a class, an interface, a constructor, a method, or field declaration.

Example: 

1
2
3
4
5
/** 
 * Encapsulates a circle on a 2D plane.  The `Circle` class supports operators 
 * supported includes (i) checking if a point is contained in the circle,
 * and (ii) moving the circle around to a new position.
 */

The first sentence is the summary sentence. We should follow some style guideline when writing the summary sentence (read on for more information).

Tags

javadoc comments supports tags. Here are some tags that we would like you to use:

  • @param <name> <description>: describes the parameter
  • @return <description> describes the return value
  • @throws <class name> <description> describes the exception being thrown possible reasons for doing so

Style

  1. If you want to break you comments into paragraphs, insert one blank line between paragraphs. Start a new paragraph with the HTML tag <p> with no trailing space, and end your paragraph with the HTML tag </p>.

  2. You should use the tags @param @return and @throws in that order, and they should never appear without a description.

  3. The summary should be short and succint. It is not a complete sentence, however, but starts with a capitalized verb (verb tense should be present tense) and ends with a period.
    E.g., /** Encapsulates a circle on 2D plane. .. */

  4. Avoid writing javadoc for self-explanatory, simple, obvious, methods. e.g., getX(), unless you want to explain what x means.

How to generate javadoc

In its simplest form, you can generate javadoc like this:

1
javadoc *.java

This will generate the documentation files in your current directory.

To avoid clutter, it is recommended that the output directory be specified, e.g.,

1
javadoc *.java -d docs

This will generate the documentation files in the docs subdirectory.

By default, javadoc only generates documents for public classes, fields, and methods. To generate full documentation, use 

1
javadoc *.java -d docs -private

How to view generate javadoc

You can view your documentation by loading up the file index.html in your browser.

See Also