Javadoc: doc comments to HTML API docs

Documentation that compiles into the API

A doc comment (Javadoc) is a special comment opened with / (two stars) placed immediately before** the element it documents — a class, interface, constructor, method, or field. The javadoc tool extracts these comments and your code's signatures to generate the browsable HTML API documentation you have read for the JDK itself (docs.oracle.com/.../api/).

Note the distinction: /* ... */ is an ordinary block comment the tool ignores; only /** ... */ is a doc comment.

Anatomy of a doc comment

The first sentence (up to the first period followed by whitespace) becomes the summary shown in member lists, so make it a crisp, self-contained statement. After the description come block tags, each starting a line with @:

/**
 * Schedules an event to fire after a delay.
 *
 * <p>The delay is measured from the moment this method is called.
 * Negative delays are treated as zero.
 *
 * @param event   the event to schedule; must not be {@code null}
 * @param delayMs the delay in milliseconds before the event fires
 * @return the unique id assigned to the scheduled event
 * @throws IllegalArgumentException if {@code event} is null
 * @see Controller#run()
 * @since 1.2
 */
public int schedule(Event event, long delayMs) {
    // ...
    return 0;
}

The block tags you are expected to use

| Tag | Where | Purpose | |---|---|---| | @param name | methods/ctors | one per parameter, in declaration order | | @return | non-void methods | what the return value means (omit for void) | | @throws (or @exception) | methods | one per documented exception + the condition | | @deprecated | any | why, and what to use instead | | @see | any | cross-reference to a related element | | @since | any | the version the element appeared | | @author, @version | classes | authorship metadata |

Inline tags go inside braces within the text: {@code list.get(0)} renders in a monospaced font without HTML-escaping issues, and {@link Controller#run()} makes a hyperlink. Standard HTML is allowed in the description (<p>, <ul><li>, <pre>).

Class-level doc comment

/**
 * Runs scheduled {@link Event}s in priority order until none remain.
 *
 * <p>Not thread-safe; confine each {@code Controller} to one thread.
 *
 * @author A. Student
 * @version 1.0
 */
public class Controller {
    // ...
}

Generating the HTML

From the command line you point javadoc at packages or source files and an output directory:

javadoc -d docs -author -version src/greenhouse/*.java

The -d flag sets the destination directory; -author and -version include those (otherwise-suppressed) tags. The result is a set of HTML pages with the package overview, class pages, and method details.

Why the project grades it

The Greenhouse Challenge Project rubric awards marks for documentation, and Unit 10 of the syllabus makes Javadoc examinable for a reason: on a team, the generated API is how *other people* use your classes without reading the source. A method whose @param/@return/@throws are complete is self-describing; one without them forces every caller to reverse-engineer the implementation. Writing the contract in the doc comment also clarifies your own design before you implement it.