Writing Javadoc — Write Javadoc comments for methods (intro) - Java

SECTION 1

Historical Context & Motivation

Imagine you write a brilliant method that calculates a student's GPA, but six months later you come back to your own code and can't remember what it does or how to use it. This exact problem plagued early software developers. As programs grew from hundreds to thousands of lines, teams needed a standard way to explain what each piece of code was supposed to do.

In the early days of programming, documentation was often written in separate text files or printed manuals. This created a constant headache: the code would change, but the documentation wouldn't get updated, leaving programmers with misleading or outdated instructions. Sun Microsystems, the creator of Java, recognized this problem and built a documentation tool directly into the Java ecosystem. That tool is called Javadoc, and it changed the way developers think about commenting their code.

1991 • Java's Origins at Sun Microsystems

James Gosling and his team at Sun Microsystems began developing the Java language, emphasizing portability, readability, and built-in documentation support.

1995 • Java 1.0 and Javadoc Released

Java 1.0 shipped with the Javadoc tool, allowing developers to generate professional HTML documentation directly from specially formatted comments in source code.

2004 • Java 5 Enhances Javadoc Tags

Java 5 introduced generics and annotations, and Javadoc was updated with new tags to document these features, making the tool even more powerful.

2014–Present • Modern IDEs Integrate Javadoc

IDEs like IntelliJ IDEA and Eclipse display Javadoc comments as pop-up tooltips, making documentation instantly accessible to anyone reading or using your code.

The central question Javadoc answers is simple but important: how can we keep documentation and code in the same file so they never go out of sync? By writing documentation comments directly above each method, you ensure that anyone — including your future self — can instantly understand what a method does, what it needs, and what it returns.

SECTION 2

Core Principles of Javadoc Comments

Before diving into the syntax, it's important to understand the core ideas that make Javadoc effective. A Javadoc comment is not just a regular comment — it follows a specific structure that the Javadoc tool can parse and convert into web-based documentation pages. Every public method you write should have one.

Starts with /** and Ends with */

A Javadoc comment begins with /** (two asterisks) and ends with */. This distinguishes it from regular comments (// or /* */), which the Javadoc tool ignores.

Placed Directly Above the Method

The comment must appear immediately before the method declaration. If you put it elsewhere, the Javadoc tool won't associate it with the method.

First Sentence = Summary

The first sentence of a Javadoc comment serves as the method's summary. It should clearly describe what the method does in one sentence, ending with a period.

Tags Describe Parameters and Return Values

Special tags like @param and @return provide structured information about the method's inputs and output.

Generates HTML Documentation

Running the javadoc command-line tool transforms your comments into browsable HTML pages, just like the official Java API documentation.

✦

KEY TAKEAWAY

Think of Javadoc comments like the label on a medicine bottle. The label tells you the drug's purpose, the dosage (parameters), and what to expect (return value). Without the label, you'd have no idea what the pill does — and without Javadoc, other programmers have no idea what your method does. Writing Javadoc is like putting a clear, accurate label on every method you create.

SECTION 3

Anatomy of a Javadoc Comment

The diagram below breaks down a complete Javadoc comment for a method. Each part is color-coded so you can see how the opening delimiter, summary sentence, tags, and closing delimiter fit together.

A full Javadoc comment sits directly above the method declaration. The opening and closing delimiters frame the comment. The summary sentence appears first, followed by @param tags for each input and a @return tag for the output.

Notice that every line inside the comment begins with a single asterisk * for readability. This is a convention, not a requirement, but all professional Java code follows it. The first sentence before the blank line is pulled out as the short summary in generated documentation. The tags after the blank line provide structured data that the Javadoc tool formats into neat tables.

SECTION 4

How the Javadoc Tool Works

Understanding the flow from source code to documentation helps you appreciate why Javadoc formatting matters. The Javadoc tool is a command-line program that ships with the Java Development Kit (JDK). When you run it against your .java files, it scans for /** */ comments, extracts the structured information, and produces HTML pages. These pages look exactly like the official Java API documentation you might already use when looking up String or ArrayList methods.

The Three Types of Java Comments

Comment Type	Syntax	Purpose
Single-line comment	`// comment text`	Quick notes for yourself; ignored by Javadoc
Multi-line comment	`/* comment text */`	Block notes for internal logic; ignored by Javadoc
Javadoc comment	`/** comment text */`	Formal documentation; processed by the Javadoc tool to create HTML

Only Javadoc comments (with two asterisks) are processed by the tool.

Essential Javadoc Tags for Methods

Tag	Syntax	When to Use
`@param`	`@param name description`	Once for each parameter the method accepts
`@return`	`@return description`	For every method that returns a value (not `void`)
`@throws`	`@throws ExceptionType description`	When the method might throw an exception (advanced usage)
`@see`	`@see ClassName#methodName`	To cross-reference related methods or classes

The @param and @return tags are the most commonly used for documenting methods.

⚠

Important Rule

The order of tags matters by convention: list all @param tags first (in the same order the parameters appear in the method signature), then @return, then @throws. Consistent ordering keeps your documentation professional and easy to read.

SECTION 5

Deep Dive into @param and @return

The two tags you'll use most often are @param and @return. Getting these right makes the difference between documentation that helps and documentation that confuses. Let's look at a visual comparison of weak and strong documentation.

The weak example uses vague language that tells the reader almost nothing. The strong example clearly states the method's purpose, specifies units for each parameter, and describes the return value. Four writing tips are listed at the bottom.

A common mistake is writing documentation that simply restates the method name: "Calculates calc." That tells the reader nothing they couldn't already figure out. Instead, focus on the purpose of the method, the meaning of each parameter (including units or valid ranges), and what the caller can expect as a return value.

SECTION 6

Worked Example — Documenting a Method from Scratch

Let's walk through writing a Javadoc comment for a method that converts a temperature from Fahrenheit to Celsius. We'll build the comment one piece at a time.

Documenting a Temperature Conversion Method

1
Step 1 — Write the Method Signature First

Start by looking at the method you need to document. The method is: public double toCelsius(double fahrenheit). It takes one double parameter and returns a double. This tells us we need one @param tag and one @return tag.

Identified: 1 parameter, 1 return value
2
Step 2 — Write the Summary Sentence

Open the comment with /** and write one clear sentence describing the method's purpose. A good summary answers: "What does this method do?"

/** Converts a temperature from Fahrenheit to Celsius.
3
Step 3 — Add the @param Tag

After a blank comment line, add the @param tag. Write the parameter name exactly as it appears in the method signature, followed by a clear description. Include units when they help.

* @param fahrenheit the temperature in degrees Fahrenheit
4
Step 4 — Add the @return Tag

Add the @return tag describing what the method gives back to the caller. Be specific about what the value represents.

* @return the equivalent temperature in degrees Celsius
5
Step 5 — Assemble the Complete Comment

Put it all together and close with */. Here is the finished Javadoc comment above the method:

/** * Converts a temperature from Fahrenheit to Celsius. * * @param fahrenheit the temperature in degrees Fahrenheit * @return the equivalent temperature in degrees Celsius */ public double toCelsius(double fahrenheit) { return (fahrenheit - 32) * 5.0 / 9.0; }

💡

Pro Tip

Most modern IDEs can auto-generate a Javadoc skeleton for you. In IntelliJ IDEA, type /** directly above a method and press Enter — the IDE will insert @param and @return stubs automatically. You just fill in the descriptions.

SECTION 7

Javadoc vs. Regular Comments — When to Use Each

Beginning programmers sometimes wonder: "If I'm already writing regular comments, why do I need Javadoc?" The answer comes down to audience and automation. Regular comments explain how the code works internally, while Javadoc comments explain what the method does from the outside — what a caller needs to know without reading the source code.

Feature	Regular Comments (// or /* */)	Javadoc Comments (/** */)
Audience	Developers reading the source code	Any developer using the method, even without seeing the source
Tool support	No automatic processing	Parsed by the Javadoc tool to create HTML docs
IDE integration	Only visible in the source file	Shown as hover tooltips in the IDE
Placement	Anywhere in the code	Directly above a class, method, or field declaration
Best used for	Explaining tricky logic inside a method body	Describing what a method does, its inputs, and its output

Use both kinds of comments, but for different purposes.

✦

KEY TAKEAWAY

Think of it like the difference between a restaurant's menu and a recipe. The Javadoc comment is the menu — it tells customers (other developers) what the dish is, what ingredients it needs (parameters), and what they'll get (return value). Regular comments are the recipe notes — internal instructions that only the chef (you, the coder) needs to see. Both are valuable, but they serve different audiences.

SECTION 8

Connection to Advanced Documentation

So far, we've focused on writing Javadoc for individual methods, which is the foundation. But Javadoc scales far beyond simple method documentation. As your projects grow, you'll encounter class-level documentation, package-level documentation, and additional tags that support more complex scenarios.

Concept	Intro Level (This Lesson)	Advanced Level (Future Topics)
Scope	Document individual methods	Document classes, interfaces, packages, and modules
Tags used	`@param`, `@return`	`@throws`, `@see`, `@since`, `@deprecated`, `@author`
HTML in comments	Plain text descriptions only	Embed HTML tags like `<code>` and `<ul>` for rich formatting
Code examples	Not included	Use `{@code ...}` and `<pre>` blocks for usage examples
Inheritance	Not applicable	Use `{@inheritDoc}` to reuse parent class documentation

This lesson covers the intro-level column. Advanced features build on the same principles.

The good news is that the skills you learn now — writing a clear summary sentence, describing parameters, and documenting return values — are exactly the same skills you'll use for more advanced Javadoc. The tags may change, but the mindset of writing for the reader, not yourself stays the same. Professional Java libraries like the Java Collections Framework and Spring Boot rely heavily on thorough Javadoc, and learning to write it well now will prepare you for real-world software development.

SECTION 9

Practice Problems

Question 1: CONCEPTUAL

What is the key difference between a regular multi-line comment /* */ and a Javadoc comment /** */? Why does the extra asterisk matter?

Show answer

A regular multi-line comment starting with /* is completely ignored by the Javadoc tool — it only serves as an internal note for anyone reading the source code. A Javadoc comment starting with /** signals the Javadoc tool to parse it and include it in the generated HTML documentation. The extra asterisk is the signal that makes the comment machine-readable. Without it, your carefully written documentation won't appear in the generated API pages or in IDE hover tooltips.

Question 2: BASIC

Write a complete Javadoc comment for the following method signature: public int add(int a, int b). The method returns the sum of a and b.

Show answer

A correct Javadoc comment would be:

/**
 * Calculates the sum of two integers.
 *
 * @param a the first integer to add
 * @param b the second integer to add
 * @return the sum of a and b
 */

Notice the summary sentence explains the method's purpose without restating the method name. Each @param tag describes what that input represents, and the @return tag tells the caller what they'll get back.

Question 3: INTERMEDIATE

A classmate writes the following Javadoc comment for a method. Identify at least two problems and rewrite it correctly.

/* Finds max.
 * @return max number
 */
public int findMax(int[] numbers)

Show answer

There are three problems. First, the comment starts with /* instead of /**, so the Javadoc tool won't process it at all. Second, the summary "Finds max" is vague and doesn't clearly explain the method's behavior. Third, the @param tag for numbers is missing entirely. A corrected version would be:

/**
 * Finds the maximum value in an array of integers.
 *
 * @param numbers the array of integers to search
 * @return the largest integer in the array
 */

Question 4: APPLIED

You are building a student grade tracker. Write both the Javadoc comment and the method signature (no body needed) for a method called calculateLetterGrade that takes a student's numeric score (a double between 0 and 100) and returns a String representing the letter grade ("A", "B", "C", "D", or "F").

Show answer

/**
 * Determines the letter grade for a given numeric score.
 *
 * @param score the student's numeric score, a value
 *              between 0.0 and 100.0 inclusive
 * @return the letter grade as a String: "A" for 90–100,
 *         "B" for 80–89, "C" for 70–79, "D" for 60–69,
 *         or "F" for below 60
 */
public String calculateLetterGrade(double score)

This answer is strong because the summary sentence explains the purpose without restating the method name. The @param tag specifies the valid range (0.0 to 100.0), which helps callers avoid passing invalid inputs. The @return tag lists all possible return values so the caller knows exactly what to expect.

Question 5: CRITICAL THINKING

Consider a method public void printReport(String studentName, int[] grades) that prints a formatted grade report to the console but doesn't return anything. How does the lack of a return value affect what you write in the Javadoc comment? Write the complete Javadoc, and explain your reasoning about the @return tag.

Show answer

/**
 * Prints a formatted grade report for a student to the
 * console, including the student's name, individual
 * grades, and their average.
 *
 * @param studentName the full name of the student
 * @param grades an array of the student's integer grades
 */

Because the method's return type is void, you should omit the @return tag entirely. Including @return for a void method would be misleading and some tools would flag it as an error. Instead, the summary sentence should clearly state the method's side effect — in this case, printing to the console. This illustrates an important principle: Javadoc should describe what the method does, whether that's returning a value or performing an action.

SUMMARY

Summary

Javadoc comments are special comments beginning with /** that the Javadoc tool converts into professional HTML documentation. Every Javadoc comment starts with a summary sentence describing what the method does, followed by @param tags for each parameter and a @return tag for the output (omitted for void methods). Place the comment directly above the method declaration.

Good Javadoc goes beyond restating the method name — it explains the purpose of the method, includes units and valid ranges in parameter descriptions, and clearly states what the return value represents. Unlike regular comments that explain internal logic, Javadoc serves external users who want to call your method without reading its source code. Mastering this skill prepares you for professional Java development and team-based coding projects.