Java 注释中的 /** 和 /*

/** and /* in Java Comments

提问by Devender

What's the difference between

有什么区别

/**
 * comment
 *
 *
 */

and

和

/*
 * 
 * comment
 *
 */

in Java? When should I use them?

在爪哇？我应该什么时候使用它们？

采纳答案by Makoto

The first form is called Javadoc. You use this when you're writing formal APIs for your code, which are generated by the javadoctool. For an example, the Java 7 API pageuses Javadoc and was generated by that tool.

第一种形式称为Javadoc。当你为你的代码编写正式的 API 时，你会使用它，这些 API 是由javadoc工具生成的。例如，Java 7 API 页面使用 Javadoc 并由该工具生成。

Some common elements you'd see in Javadoc include:

您会在 Javadoc 中看到的一些常见元素包括：

• @param: this is used to indicate what parameters are being passed to a method, and what value they're expected to have

• @return: this is used to indicate what result the method is going to give back

• @throws: this is used to indicate that a method throws an exception or error in case of certain input

• @since: this is used to indicate the earliest Java version this class or function was available in

• @param：这用于指示将哪些参数传递给方法，以及期望它们具有什么值

• @return: 这用于指示该方法将返回什么结果

• @throws: 这用于指示某个方法在某些输入的情况下抛出异常或错误

• @since: 这用于指示该类或函数在其中可用的最早 Java 版本

As an example, here's Javadoc for the comparemethod of Integer:

例如，这里是compare方法的 Javadoc Integer：

/**
 * Compares two {@code int} values numerically.
 * The value returned is identical to what would be returned by:
 * <pre>
 *    Integer.valueOf(x).compareTo(Integer.valueOf(y))
 * </pre>
 *
 * @param  x the first {@code int} to compare
 * @param  y the second {@code int} to compare
 * @return the value {@code 0} if {@code x == y};
 *         a value less than {@code 0} if {@code x < y}; and
 *         a value greater than {@code 0} if {@code x > y}
 * @since 1.7
 */
public static int compare(int x, int y) {
    return (x < y) ? -1 : ((x == y) ? 0 : 1);
}

The second form is a block (multi-line) comment. You use this if you want to have multiple lines in a comment.

第二种形式是块（多行）注释。如果您想在注释中包含多行，请使用此选项。

I will say that you'd only want to use the latter form sparingly; that is, you don't want to overburden your code with block comments that don't describe what behaviors the method/complex function is supposed to have.

我会说你只想谨慎地使用后一种形式；也就是说，您不想使用未描述方法/复杂函数应该具有的行为的块注释使代码负担过重。

Since Javadoc is the more descriptive of the two, and you can generate actual documentation as a result of using it, using Javadoc would be more preferable to simple block comments.

由于 Javadoc 是两者中更具描述性的，并且您可以通过使用它来生成实际文档，因此使用 Javadoc 比简单的块注释更可取。

回答by M Anouti

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

第一个是 Javadoc 注释。该javadoc工具可以处理它们以生成类的 API 文档。第二个是普通的块注释。

回答by Ranjeet

Java supports two types of comments:

Java 支持两种类型的注释：

• /* 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.

• /* multiline comment */：编译器忽略从/*到的所有内容*/。注释可以跨越多行。

• // single line: 编译器忽略从//到行尾的所有内容。

Some tool such as javadocuse 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.

某些工具（例如javadoc）使用特殊的多行注释来达到目的。例如/** doc comment */，javadoc 在准备自动生成的文档时使用的文档注释，但对于 Java，它是一个简单的多行注释。

回答by Raj

Comments in the following listing of Java Code are the greyed out characters:

以下 Java 代码列表中的注释是灰色字符：

/** 
 * The HelloWorldApp class implements an application that
 * simply displays "Hello World!" to the standard output.
 */
class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); //Display the string.
    }
}

The Java language supports three kinds of comments:

Java 语言支持三种注释：

/* text */

The compiler ignores everything from /*to */.

编译器会忽略从/*到 的所有内容*/。

/** documentation */

This indicates a documentation comment (doc comment, for short). The compiler ignores this kind of comment, just like it ignores comments that use /*and */. The JDK javadoc tool uses doc comments when preparing automatically generated documentation.

这表示文档注释（简称 doc 注释）。编译器会忽略这种注释，就像忽略使用/*和的注释一样*/。JDK javadoc 工具在准备自动生成的文档时使用文档注释。

// text

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

编译器忽略从//到行尾的所有内容。

Now regarding when you should be using them:

现在关于您应该何时使用它们：

Use // textwhen you want to comment a single line of code.

使用// text时，您要评论的一行代码。

Use /* text */when you want to comment multiple lines of code.

使用/* text */时，您要评论的多行代码。

Use /** documentation */when you would want to add some info about the program that can be used for automatic generation of program documentation.

使用/** documentation */时，你会想加入，可用于自动生成程序文档的程序的一些信息。

回答by sunny

First one is for Javadoc you define on the top of classes, interfaces, methods etc. You can use Javadoc as the name suggest to document your code on what the class does or what method does etc and generate report on it.

第一个是用于在类、接口、方法等顶部定义的 Javadoc。顾名思义，您可以使用 Javadoc 来记录您的代码，说明类的作用或方法的作用等，并生成有关它的报告。

Second one is code block comment. Say for example you have some code block which you do not want compiler to interpret then you use code block comment.

第二个是代码块注释。例如，假设您有一些不希望编译器解释的代码块，然后您使用代码块注释。

another one is // this you use on statement level to specify what the proceeding lines of codes are supposed to do.

另一个是 // 您在语句级别使用它来指定后续代码行应该做什么。

There are some other also like //TODO, this will mark that you want to do something later on that place

还有一些其他的也像//TODO，这将标志着你想稍后在那个地方做一些事情

//FIXME you can use when you have some temporary solution but you want to visit later and make it better.

//FIXME 当您有一些临时解决方案但您想稍后访问并使其更好时可以使用。

Hope this helps

希望这可以帮助

回答by Hoopje

For the Java programming language, there is no differencebetween the two. Java has two types of comments: traditional comments (/* ... */) and end-of-line comments (// ...). See the Java Language Specification. So, for the Java programming language, both /* ... */and /** ... */are instances of traditional comments, and they are both treated exactly the same by the Java compiler, i.e., they are ignored (or more correctly: they are treated as white space).

对于 Java编程语言，两者没有区别。Java 有两种类型的注释：传统注释 ( /* ... */) 和行尾注释 ( // ...)。请参阅Java 语言规范。因此，对于 Java 编程语言，/* ... */和/** ... */都是传统注释的实例，Java 编译器对它们的处理完全相同，即它们被忽略（或更准确地说：它们被视为空白）。

However, as a Java programmer, you do not only use a Java compiler. You use a an entire tool chain, which includes e.g. the compiler, an IDE, a build system, etc. And some of these tools interpret things differently than the Java compiler. In particular, /** ... */comments are interpreted by the Javadoc tool, which is included in the Java platformand generates documentation. The Javadoc tool will scan the Java source file and interpret the parts between /** ... */as documentation.

但是，作为 Java 程序员，您不仅仅使用 Java 编译器。您使用一个完整的工具链，其中包括例如编译器、IDE、构建系统等。其中一些工具的解释方式与 Java 编译器不同。特别是，/** ... */注释由 Javadoc 工具解释，该工具包含在 Java平台中并生成文档。Javadoc 工具将扫描 Java 源文件并将其中的部分解释/** ... */为文档。

This is similar to tags like FIXMEand TODO: if you include a comment like // TODO: fix thisor // FIXME: do that, most IDEs will highlight such comments so that you don't forget about them. But for Java, they are just comments.

这类似于标签FIXME和TODO：如果您包含像// TODO: fix this或// FIXME: do that这样的注释，大多数 IDE 会突出显示此类注释，以便您不会忘记它们。但是对于 Java，它们只是注释。

回答by Jean-Fran?ois Savard

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

阅读JLS 的 3.7节很好地解释了您需要了解的有关 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++).

有两种评论：

• /* 文本 */

传统注释：从 ASCII 字符 /* 到 ASCII 字符 */ 的所有文本都被忽略（如在 C 和 C++ 中）。

• //文本

行尾注释：从 ASCII 字符 // 到行尾的所有文本都将被忽略（如在 C++ 中）。

---

---

About your question,

关于你的问题，

The first one

第一个

/**
 *
 */

is used to declare Javadoc Technology.

用于声明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.

Javadoc 是一种工具，它解析一组源文件中的声明和文档注释，并生成一组描述类、接口、构造函数、方法和字段的 HTML 页面。您可以使用 Javadoc doclet 来定制 Javadoc 输出。doclet 是用 Doclet API 编写的程序，它指定了该工具要生成的输出的内容和格式。您可以编写 doclet 来生成任何类型的文本文件输出，例如 HTML、SGML、XML、RTF 和 MIF。Oracle 提供了用于生成 HTML 格式 API 文档的标准 doclet。Doclet 还可用于执行与生成 API 文档无关的特殊任务。

For more information on Docletrefer to the API.

有关更多信息，Doclet请参阅API。

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

第二个，正如在 JLS 中清楚解释的那样，将忽略之间的所有文本/*，*/因此用于创建多行注释。

---

---

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

关于 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).

• 评论不嵌套。
• /* and */在以//.开头的注释中没有特殊含义。
• //在以/* or /**.开头的注释中没有特殊含义。
• 词法语法暗示注释不会出现在字符文字 ( §3.10.4) 或字符串文字 ( §3.10.5) 中。

Thus, the following text is a single complete comment:

因此，以下文本是一个完整的评论：

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

回答by Kevin Krumwiede

I don't think the existing answers adequately addressed this part of the question:

我认为现有的答案没有充分解决问题的这一部分：

When should I use them?

我应该什么时候使用它们？

If you're writing an API that will be published or reused within your organization, you should write comprehensive Javadoc comments for every publicclass, method, and field, as well as protectedmethods and fields of non-finalclasses. Javadoc should cover everything that cannotbe conveyed by the method signature, such as preconditions, postconditions, valid arguments, runtime exceptions, internal calls, etc.

如果您正在编写将在您的组织内发布或重用的 API，您应该为每个public类、方法和字段以及protected非final类的方法和字段编写全面的 Javadoc 注释。Javadoc 应该涵盖方法签名无法传达的所有内容，例如前置条件、后置条件、有效参数、运行时异常、内部调用等。

If you're writing an internal API (one that's used by different parts of the same program), Javadoc is arguably less important. But for the benefit of maintenance programmers, you should still write Javadoc for any method or field where the correct usage or meaning is not immediately obvious.

如果您正在编写内部 API（由同一程序的不同部分使用的 API），则 Javadoc 可以说不那么重要。但是为了维护程序员的利益，您仍然应该为正确用法或含义不是很明显的任何方法或字段编写 Javadoc。

The "killer feature" of Javadoc is that it's closely integrated with Eclipse and other IDEs. A developer only needs to hover their mouse pointer over an identifier to learn everything they need to know about it. Constantly referring to the documentation becomes second nature for experienced Java developers, which improves the quality of their own code. If your API isn't documented with Javadoc, experienced developers will not want to use it.

Javadoc 的“杀手级特性”是它与 Eclipse 和其他 IDE 紧密集成。开发人员只需将鼠标指针悬停在标识符上即可了解他们需要了解的所有信息。不断参考文档成为有经验的 Java 开发人员的第二天性，这提高了他们自己的代码质量。如果您的 API 没有用 Javadoc 记录，那么有经验的开发人员将不会想要使用它。

回答by Ramlal S

• Single comment e.g.: //comment
• Multi Line comment e.g: /* comment */
• javadoc comment e.g: /** comment */

• 单条评论例如：//评论
• 多行注释 例如：/* 注释 */
• javadoc 注释 例如：/** 注释 */