3.7 Comments

Java defines three kinds of comments:

/* text */ A traditional comment: all the text from the ASCII characters /* to the ASCII characters */ is ignored (as in C and C++).

// text A single-line comment: all the text from the ASCII characters // to the end of the line is ignored (as in C++).

/** documentation */ A documentation comment: the text enclosed by the ASCII characters /** and */ can be processed by a separate tool to prepare automatically generated documentation of the following class, interface, constructor, or member (method or field) declaration. See §18 for a full description of how the supplied documentation is processed.

These comments are formally specified by the following productions:

Comment:

	TraditionalComment

	EndOfLineComment

	DocumentationComment

TraditionalComment:

	/ * NotStar CommentTail

EndOfLineComment:

	/ / CharactersInLineopt LineTerminator

DocumentationComment:

	/ * * CommentTailStar

CommentTail:

	* CommentTailStar

	NotStar CommentTail

CommentTailStar:

	/

	* CommentTailStar

	NotStarNotSlash CommentTail

NotStar:

	InputCharacter but not *

	LineTerminator

NotStarNotSlash:

	InputCharacter but not * or /

	LineTerminator

CharactersInLine:

	InputCharacter

	CharactersInLine InputCharacter

These productions imply all of the following properties:

• Comments do not nest.
• /* and */ have no special meaning in comments that begin with //.
• // has no special meaning in comments that begin with /* or /**.

As a result, the text:

/* this comment /* // /** ends here: */

is a single complete comment.

The lexical grammar implies that comments do not occur within character literals (§3.10.4) or string literals (§3.10.5).

Note that /**/ is considered to be a documentation comment, while /* */ (with a space between the asterisks) is a traditional comment.