Javadoc

A comment style that explains what your code does — written for the next person who reads it, who might just be you, later.

/**
 * Counts how many vowels appear in a phrase, ignoring case.
 *
 * @param phrase the text to check
 * @return the number of vowels found
 */
static int solve(String phrase) { ... }

Three Comment Types

Java gives you three ways to leave a note in your code. Each one exists for a different job.

One

Line comment

// checks each vowel one at a time

Starts with //, ends at the end of the line. Good for a quick note on one specific piece of code.

Two

Block comment

/* This whole method works by
   comparing string lengths
   before and after removing
   each vowel. */

Starts with /*, ends with */. Can span multiple lines — good for a longer explanation.

Three

Javadoc comment

/**
 * @param phrase text to check
 * @return vowel count
 */

Starts with /** — one extra star. Sits directly above a method, and can generate real documentation pages automatically.

Javadoc Tags

A Javadoc comment isn't just prose — it uses specific tags that describe a method's pieces individually, so tools (and people) can pull out exactly what they need.

TagDescribesExample
@paramone parameter, by name@param phrase the text to check
@returnwhat comes back, and when@return the number of vowels found
@throwsan exception the method can raise@throws NullPointerException if phrase is null
/** * Counts how many vowels appear in a phrase, ignoring case. * * @param phrase the text to check * @return the number of vowels found */ static int solve(String phrase) { String lower = phrase.toLowerCase(); int count = 0; count += lower.length() - lower.replace("a", "").length(); count += lower.length() - lower.replace("e", "").length(); count += lower.length() - lower.replace("i", "").length(); count += lower.length() - lower.replace("o", "").length(); count += lower.length() - lower.replace("u", "").length(); return count; }
Why comment this one specifically?
The technique — subtracting a modified string's length from the original — isn't obvious just from reading the code. The Javadoc doesn't need to explain how the trick works line by line; that's what an inline // comment is for. It just needs to say what the method does, in case someone's only reading the signature.

Preconditions & Postconditions

Good documentation doesn't just describe what a method does — it describes what has to be true before you call it, and what's guaranteed once it's done.

TermMeans
preconditionwhat must be true before the method is called, for it to work correctly
postconditionwhat's guaranteed to be true after the method finishes

For solve(String phrase) above: the precondition is that phrase isn't null — calling .toLowerCase() on null would crash. The postcondition is that the returned number is never negative, since you can't have fewer than zero vowels.

Before & After

The exact same code, correct either way — but only one version tells you anything before you've read every line.

Before
static String solve(String word) {
    return word.charAt(0) + ""
        + word.charAt(word.length() - 1);
}
After
/**
 * Combines a word's first and
 * last character.
 *
 * @param word the word to shorten
 * @return the first and last
 *         letter, concatenated
 */
static String solve(String word) {
    return word.charAt(0) + ""
        + word.charAt(word.length() - 1);
}

Running javadoc

Writing the comment is only half of it. javadoc is a real command-line tool that reads every Javadoc comment in a file and builds an actual browsable HTML documentation page from it — the same way official Java library docs get made.

$ javadoc vowelcount.java Loading source files for package unnamed package... Constructing Javadoc information... Standard Doclet version 21+35-2513 Building tree for all the packages and classes... Generating index.html... Building index for all the packages and classes... Generating overview-tree.html... 1 warning

That "1 warning" at the end is normal — javadoc often flags small things like a missing package declaration in a single-file project. It doesn't stop the docs from generating.

index.html vowelcount.html allclasses-index.html overview-tree.html ...
What just got created
A whole folder of new HTML files appears next to your .java file. index.html is the entry point — open that first, then click through to your class's own page (named after your class, like vowelcount.html) to see your @param and @return text rendered as an actual formatted reference page.

If a class has more than one method — including overloaded methods that share a name — each one gets listed separately on that class's page, with its own description, right below the others.