Unit 1.8: Documentation with Comments

Comments

Comments are notes in your source code that are ignored by the compiler. They are intended for programmers to read and understand the code.

• Single-line comment (//): For short notes.
• Multi-line comment (/* */): For longer explanations.
• Javadoc comment (/** */): A special type of multi-line comment used to generate professional API documentation in HTML format.
  • It starts with /** (two asterisks) and ends with */.
  • Javadoc comments are placed immediately above classes, interfaces, or methods.
  • They use special "tags" starting with @ to provide structured information.

Task: Using different types of comments in a class.

/**
 * This class represents a simple calculator.
 */
public class Calculator {
    // This is a single-line comment
    
    /*
     This method adds two integers.
     It's a multi-line comment.
    */
    public int add(int a, int b) {
        return a + b;
    }
}

Common Javadoc Tags

Javadoc uses specific tags to organize documentation:

• @param: Describes a method parameter (input).
• @return: Describes the value the method returns.
• @precondition: (As discussed below) Describes what must be true before the call.
• @postcondition: (As discussed below) Describes what is guaranteed after the call.

When you hover over a method in an IDE (like Eclipse or VS Code), it reads these Javadoc comments and displays them to you, helping you understand how to use the method without looking at the source code.

Precondition

A precondition is a condition that must be true before a method is called for it to work correctly. It is the responsibility of the programmer calling the method to ensure the precondition is met.

Task: Documenting a method precondition with Javadoc.

/**
 * Calculates the square root of a number.
 * @param x The number to find the square root of.
 * @precondition x >= 0
 * @return The square root of x.
 */
public double sqrt(double x) {
    // ... implementation ...
}

Postcondition

A postcondition is a condition that is guaranteed to be true after a method has finished executing (assuming the preconditions were met). It describes the outcome of the method.

Task: Documenting a method postcondition with Javadoc.

/**
 * Increments the score by one.
 * @postcondition The score is increased by 1.
 */
public void incrementScore() {
    // ... implementation ...
}

Official Javadoc

Javadoc for the java.lang package

If you are using an IDE like Eclipse, the Javadoc for each of the JDK classes will be available when you type a . after the class name. For example, type Math followed by a .. What do you see?

Math.

You will see a drop-down menu with all available methods that you can use with Math. Selecting any specific method will provide more documentation for that method.