/** and /* in Java Comments

Question

What's the difference between

/**
 * comment
 *
 *
 */

and

/*
 * 
 * comment
 *
 */

in Java? When should I use them?

Answer 1

The first is Javadoc comments. They can be processed by the javadoc tool to generate the API documentation for your classes. The second is a normal block comment.

Answer 2

Java supports two types of comments:

• /* multiline comment */ : The compiler ignores everything from /* to */. The comment can span over multiple lines.

• // single line : The compiler ignores everything from // to the end of the line.

Some tool such as javadoc use a special multiline comment for their purpose. For example /** doc comment */ is a documentation comment used by javadoc when preparing the automatically generated documentation, but for Java it's a simple multiline comment.

Answer 3

Reading the section 3.7 of JLS well explain all you need to know about comments in Java.

There are two 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

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

---

About your question,

The first one

/**
 *
 */

is used to declare Javadoc Technology.

Javadoc is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the classes, interfaces, constructors, methods, and fields. You can use a Javadoc doclet to customize Javadoc output. A doclet is a program written with the Doclet API that specifies the content and format of the output to be generated by the tool. You can write a doclet to generate any kind of text file output, such as HTML, SGML, XML, RTF, and MIF. Oracle provides a standard doclet for generating HTML-format API documentation. Doclets can also be used to perform special tasks not related to producing API documentation.

For more information on Doclet refer to the API.

The second one, as explained clearly in JLS, will ignore all the text between /* and */ thus is used to create multiline comments.

---

Some other things you might want to know about comments in Java

• Comments do not nest.
• /* and */ have no special meaning in comments that begin with //.
• // has no special meaning in comments that begin with /* or /**.
• The lexical grammar implies that comments do not occur within character literals (§3.10.4) or string literals (§3.10.5).

Thus, the following text is a single complete comment:

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