Javadoc: Reading and Writing Documentation

Discussion prompt

From Lesson 1b: what is a comment, and what does the compiler do with one? From Lesson 3a: which library class did you use to read input? And from Lesson 17a: what happens when a method's argument is invalid?

Hint: It is ignored entirely. And an exception is thrown.

Annotate

• Consistency is the whole argument. A separate manual drifts out of date; a comment three lines above the method is hard to miss when you change it.
• You can write it as you go, which means it exists at all — documentation deferred until later is documentation that never happens.
• javadoc is in the JDK, alongside javac — so generating documentation needs no extra installation.
• In fact, the official documentation for the Java library is generated by Javadoc from exactly this kind of comment.
• Which means the pages you read and the pages you write are the same thing. Reading library documentation teaches you what to write.

Predict first

Which one is a documentation comment?

• /** — two stars to open, one to close
• /* — one star
• Both
• Neither; documentation uses //

Correct: /** — two stars to open, one to close

Why: They begin with / (two stars) and end with / (one star).* The asymmetry is worth noticing — the closing delimiter is the same for both kinds, so only the opening tells you which you are reading.

Sort into buckets

Sort each piece of text.

// end-of-line

a note about why one line looks odd

/* multiline */

a copyright and licence

/** documentation */

what a method does, for its callers; the purpose of a class

eol

A short phrase explaining a specific line, for someone reading the source.

multi

Multiline text that is not documentation — using /** would put the whole licence in the generated HTML.

doc

Written for people who will use the class or method without reading its body, and extracted by javadoc.

Fill in the blanks

/**
* Prints a greeting.
*/
public static void main(String[] args) {

Why: Two stars open a documentation comment and one closes it. The leading * on the middle lines is conventional formatting rather than syntax — javadoc strips it, and the comment would work without it.

Discussion prompt

End-of-line comments are written primarily for yourself; documentation comments are written for others. What follows from that about how each should be written?

Hint: What can each reader see?

Annotate

• The narrative is written for every reader at once, including people who know far more than you — so some of it will not land, and that is expected.
• The examples are the entry point. They are short, complete, and written by someone who knows the class well.
• Paste, compile, run — then change one thing and see what happens. That is Lesson 4b's incremental development applied to learning a class.
• It might take you some time to get comfortable reading documentation and learning which parts to ignore.
• But it's worth the effort. Knowing what's available in the library helps you avoid reinventing the wheel.

Predict first

Is int part of nextInt's signature?

• No — the signature is the name and parameters only
• Yes — everything on the first line is the signature
• Only for static methods
• Only when the method returns an object

Correct: No — the signature is the name and parameters only

Why: The first line is the method's signature, which specifies the name of the method and its parameters. The type it returns (int) is not part of the signature. That is why overloading works on parameter lists — two methods differing only in return type would have the same signature and could not coexist.

Sort into buckets

Sort each question by where it is answered.

Constructor Summary

how do I create one of these?

Returns

what does this method give back?

Throws

what can go wrong?

the narrative

what is this class for?

ctor

Ways of creating, or constructing, an object of this class — often several, overloaded by parameter type.

ret

The result when the method succeeds.

thr

The errors and exceptions that may occur — the half that is easy to skip and expensive to skip.

nar

The purpose of the class, with examples, which are usually the best place to start.

Predict first

Where does this Scanner read from?

• The contents of the string, as if they had been typed
• A file named by the string
• The keyboard, with the string as a prompt
• It does not compile

Correct: The contents of the string, as if they had been typed

Why: Scanner has several overloaded constructors, and this one tokenises the string itself. It is immediately useful for testing input-handling code without redirection — and there is no way to discover it except by reading the documentation.

Discussion prompt

Trial and error works for simple methods. What does reading the documentation give you that experimenting does not?

Hint: What did you not think to try?

Annotate

• What, not how. A caller needs to know that toMetric converts feet and inches to centimetres, not that it multiplies by 2.54.
• Which is also what makes the comment durable. Change the implementation and a how comment is wrong; a what comment still holds.
• Complete sentences, because the reader has no surrounding context to lean on.
• Appropriate comments and documentation are essential for making source code readable.
• And remember that the person most likely to read your code in the future, and appreciate good documentation, is you.

Predict first

What is wrong here?

• The import separates the comment from the class, so the class is undocumented
• Imports must come after the class declaration
• The comment needs a @class tag
• Nothing — javadoc skips imports

Correct: The import separates the comment from the class, so the class is undocumented

Why: **A common mistake that beginners make is to put import statements between the documentation and the public class line. Doing so separates the documentation from the class itself. To avoid this issue, always make the end of the comment (the /) touch the word public.*

Sort into buckets

Sort each declaration.

document it

public static double toMetric(int feet, int inches); a public class

self-explanatory

public static final double CM_PER_INCH = 2.54;; public static final int IN_PER_FOOT = 12;

yes

A caller cannot tell from the signature what it does or what the parameters mean, so the documentation supplies the meaning.

no

The name says everything — the constants are self-explanatory, so there is no need to write documentation for them.

Fill in the blanks

/**
* Converts a measurement in centimeters to inches.
*
* @param cm length in centimeters
* @return length in inches
*/
public static double toImperial(double cm) {

Why: One @param per parameter, naming it and saying what it means, then one @return describing what comes back. Note both mention units — which is exactly the information the signature's double cannot carry.

Discussion prompt

A documentation comment explains what a method does and omits how it works. Why leave out the part you probably found hardest to write?

Hint: Who is reading, and what happens when you rewrite the body?

Annotate

• No hyphen after @param. Javadoc adds one when it generates the HTML, so writing your own gives you two.
• @return describes the value, not the type. the int scanned from the input, not int.
• One @param per parameter, each naming the parameter and then describing it.
• No @return on a void method — there is nothing to describe, which is why main's comment has only a @param.
• One tag per line, which keeps the generated page readable and the source diffable.

Predict first

How many @param tags should the comment have?

• Two — one per parameter, each on its own line
• One, listing both
• None
• Three

Correct: Two — one per parameter, each on its own line

Why: Methods with multiple parameters should have separate @param tags that describe each one. Each tag should be on its own line in the source code — which keeps the generated table readable and gives each parameter its own row.

Predict first

What is the problem?

• It names the type instead of describing the value, which the signature already gave
• @return is not a valid tag
• It should be @returns
• boolean methods do not need documentation

Correct: It names the type instead of describing the value, which the signature already gave

Why: Comments like @return boolean are not useful, because you already know the return type from the method's signature. The useful version says what the value means — true if x has one digit, false otherwise — which is the thing the type cannot express.

Match the pairs

• a. @author
• b. @version
• c. @param
• d. @return

• r1. who wrote the class
• r2. which release this is
• r3. what one parameter means
• r4. what the method gives back

Why: The first two document a class; the last two document a method. Note @author may appear more than once — the Convert example has two, one per author, each on its own line.

Discussion prompt

The appendix says generally. When would a documentation comment add nothing, and what does Checkstyle's Missing a Javadoc comment warning miss about that?

Hint: The Convert constants have none.

Predict first

Why not use /** here?

• It is not documentation, so it should not appear in the generated pages
• Licences cannot contain the * character
• javadoc rejects long comments
• It would document the imports

Correct: It is not documentation, so it should not appear in the generated pages

Why: *This text spans multiple lines, but it is not part of the documentation. So we use a multiline comment (/) rather than a documentation comment (/). Using two stars would put the entire licence at the top of the class's HTML page, ahead of anything a reader wants.

Sort into buckets

Sort each by position.

first

the copyright statement

second

import statements

third

the class documentation comment

fourth

public class Convert {

1

Professional-grade source files often begin with a copyright statement, in a plain multiline comment.

2

Import statements generally follow the copyright text.

3

The documentation comment must be adjacent to what it documents, so it comes after the imports.

4

The class declaration itself — and the comment's */ should touch the word public.

Fill in the blanks

/**
* Utility class for extracting digits from integers.
*
* @author Chris Mayfield
* @version 1.0
*/
public class DigitUtil {

Why: @author and @version are class-level tags, separated from the description by a blank line. @author may be repeated — the Convert example has two, one per author, each on its own line.

Discussion prompt

Java's library documentation is enormous and generated from comments in the source. What would using the library be like without it, and what does that say about your own code?

Hint: How would you learn what Scanner does?

Comparison matrix

Check your understanding

Which is a documentation comment, and what is the other typically used for?

• A. /** is documentation; /* is a multiline comment, typically a copyright statement (correct)
• B. /* is documentation; /** is a nested comment
• C. Both are documentation; the second is just shorter
• D. Neither; documentation uses //

Answer: A

Why: Documentation comments start with / and end with /. Multiline comments start with / and end with /, and are typically used for copyright statements.* The distinction matters because javadoc reads one and ignores the other — putting a licence in /** would print the whole thing at the top of the generated page.

Why B tempts people

This reverses them, and Java has no nested comments.

Why C tempts people

Only the two-star form is extracted; the difference is not length.

Why D tempts people

End-of-line comments are for short notes to yourself and are never extracted.

Check your understanding

What is a method's signature?

• A. Its name and parameters — the return type is not part of it (correct)
• B. The whole first line, including the return type
• C. The name only
• D. The name, parameters and return type

Answer: A

Why: The first line is the method's signature, which specifies the name of the method and its parameters (none). The type it returns (int) is not part of the signature. This is why overloading distinguishes methods by their parameter lists: two methods that differed only in return type would have identical signatures and could not both exist.

Why B tempts people

The first line includes the return type, but the signature is a narrower idea.

Why C tempts people

Parameters are part of it — that is what makes overloading possible.

Why D tempts people

The return type is explicitly excluded.

Check your understanding

Why is there no @return tag?

• A. The method is void, so there is no value to describe (correct)
• B. main never returns
• C. @return is only for private methods
• D. It was left out by mistake

Answer: A

Why: Void methods should have no @return tag, since they do not return a value. Note also what the comment does right: @param args command-line arguments with no hyphen, since javadoc adds one when it generates the HTML, and each tag on its own line.

Why B tempts people

main returns normally when it finishes; being void is the reason, not the running.

Why C tempts people

@return applies to any method that returns a value, whatever its visibility.

Why D tempts people

Its absence is correct and deliberate — the book points it out.

Discussion prompt

Why does the quality of a library's documentation matter as much as the quality of its code — and what does that mean for a class you write?

Hint: What can people do with code they cannot understand?

Predict first

Why should a @return tag not name the method's return type?

• Because the signature already gives the type; the tag should describe what the value means
• Because javadoc rejects type names in tags
• Because the return type may change
• Because @return is only for object types

Correct: Because the signature already gives the type; the tag should describe what the value means

Why: Comments like @return boolean are not useful, because you already know the return type from the method's signature. The useful version says what the value means — true if x has one digit, false otherwise — which is exactly what a type cannot express. That is the same principle behind the whole appendix: documentation supplies what the code cannot say for itself, which is why the constants in Convert need none and a method taking two bare ints does.

Discussion prompt

A classmate has written a comment above their class and cannot see it in the generated documentation. Walk them through the two most likely causes.

Hint: Count the stars, and look at what comes next.

Predict first

What is the difference between an end-of-line comment and a documentation comment?

• An end-of-line comment explains a specific line for someone reading the source; a documentation comment explains what a class or method does, for people who will use it without reading the source
• One is longer than the other
• Documentation comments are removed by the compiler and end-of-line comments are not
• Documentation comments can only appear inside methods

Correct: An end-of-line comment explains a specific line for someone reading the source; a documentation comment explains what a class or method does, for people who will use it without reading the source

Why: End-of-line and multiline comments are written primarily for yourself. Documentation comments, on the other hand, are written for others. The audience decides everything else: an end-of-line comment can be a fragment because its reader can see the surrounding code, while a documentation comment must be complete sentences explaining what, not how, because its reader has only the signature and your words. Both are ignored by the compiler; only the /** form is extracted by javadoc into HTML.

Draw it

Write out the top of a source file in order — copyright, imports, class documentation, class declaration — using the right comment form for each and marking where the */ must touch. Beside it, write a complete documentation comment for a two-parameter method that returns a value, with a description, a blank line and the tags. Then draw the arrow from each part of that comment to where it appears on the generated HTML page. Finish by listing the five tag rules: no hyphen, no type in @return, one @param each, none for void, one per line.