Documentation Comments - Beginning Java 8 Fundamentals - page 731

A block tag starts with an @ character, which is followed by the tag name. The tag text follows the tag name.
The following is an example of a block tag, which uses @author block tag and "Kishori Sharan" as the tag text:

@author Kishori Sharan

A block tag must appear in the beginning of a line in a documentation comment. Note that the asterisks, white
spaces, and the /** characters are ignored by the javadoc tool if they appear in the beginning of a line. When I state
that a block tag must appear in the beginning of a line, I mean the beginning of a line after ignoring these characters.
The following is an example of using @author and @since block tags. The @author tag lets you specify an author name
and the @since tag allows you to specify the version since the API was introduced.

/**
* A utility class to perform basic calculations on numbers.
* All methods in this class are <code>static</code>. It
* provides methods to perform addition, subtraction, multiplication, and division.
*
* @author Kishori Sharan
* @since Version 1.0
*/
public final class Calc {
// code
}

If a line in a documentation comment starts with an @ character, it will be interpreted as the start of a block tag.
If you want to start a line with an @ character without getting it interpreted as the start of a block tag, you need to use
the HTML entity &#064 instead of the @ character. However, an @ character may appear as part of the text inside a line,
provided the prior character isn't a {, which is explained more below.
The associated text with a block tag may appear in multiple lines, which includes all text that follows the tag
name until another block tag or the end of the documentation comment is encountered.
An inline tag can appear anywhere in the documentation comment where text can appear. It is of the form

{@tagName tagText}

An inline tag is enclosed inside braces ( { and } ). The following is an example of a documentation comment that
uses a {@code text} inline tag to display the text "n1 + n2" in code font:

/**
* An example of inline tag. It computes {@code n1 + n2}.
*/

■ When you are writing documentation comment, make sure that the first sentence of the description selection
of the comment is a summary sentence. the comment for a package, a class, and a member is split into two sections:
a summary section and a detail section. the first sentence of the comment is displayed in the summary section and the
entire comment is displayed in the detail section in the documentation.

Tip