Javadoc & coding standards (recap)

Doc comments, the @param/@return/@throws tags, and why the project grades documentation.

Why documentation is graded

The COMP 308 Challenge Project (the Greenhouse control system) carries marks for documentation, and Unit 10 examines Javadoc directly. So this “recap” is genuinely exam-relevant: you must be able to read and write a correct doc comment.

Three comment forms

// line comment        -- ignored by the compiler
/* block comment */    -- ignored by the compiler
/** doc comment */     -- read by the javadoc tool to generate HTML API docs

Only the / ... */ form is a Javadoc comment. It must sit immediately before** the class, field, constructor, or method it documents (no code in between).

The standard block tags

Inside a doc comment, the first sentence is a summary, then block tags describe the contract:

- @param name description — one per parameter, in declaration order. - @return description — what the method returns (omit for void). - @throws Type description (or @exception) — each exception the caller should expect. - @author, @version, @since, @deprecated, {@code ...}, {@link ...} — supporting tags.

A fully documented method header (worked example)

/**
 * Returns the average of two integers, rounding toward zero.
 *
 * @param a the first value
 * @param b the second value
 * @return the integer mean of {@code a} and {@code b}
 * @throws ArithmeticException never (kept for illustration)
 */
public int average(int a, int b) {
    return (a + b) / 2;
}

Note the shape: a one-line summary sentence, a blank line, then the tags grouped @param → @return → @throws. The javadoc tool turns this into browsable HTML; an IDE shows it on hover.

Coding-standard conventions the rubric expects

- Class names UpperCamelCase (GreenhouseControls); methods/fields/variables lowerCamelCase (eventList, addEvent); constants UPPER_SNAKE_CASE (MAX_SIZE); packages all-lowercase (com.example.greenhouse). - One top-level public class per file, and the filename must match that class name (Event.java holds public class Event). - Consistent indentation, braces, and meaningful names — readability is part of the documentation mark.

Generating the docs

Running javadoc -d docs *.java produces an HTML site under docs/. The project asks for this so a grader can browse your API the same way the standard library docs read.