Java评论中的/**和/*

Question

有什么区别

/**
 * comment
 *
 *
 */

和

/*
 * 
 * comment
 *
 */

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

Answer 1

第一种形式称为Javadoc.当您为代码编写正式API时,可以使用此代码,这些API由javadoc工具生成.例如,Java 7 API页面使用Javadoc并由该工具生成.

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

• @param:这用于指示传递给方法的参数,以及它们预期具有的值

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

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

• @since:这用于表示此类或函数可用的最早Java版本

举个例子,这里是Javadoc的compare方法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);
}

第二种形式是块(多行)注释.如果要在注释中包含多行,请使用此选项.

我会说你只想谨慎使用后一种形式; 也就是说,您不希望使用块注释来使代码过载,这些注释不描述方法/复杂函数应具有的行为.

由于Javadoc对两者的描述性更强,并且您可以使用它生成实际文档,因此使用Javadoc将比简单块注释更可取.

Answer 2

对于Java 编程语言,两者之间没有区别.Java有两种类型的注释:传统注释(/* ... */)和行尾注释(// ...).请参阅Java语言规范.因此,对于Java编程语言,无论是/* ... */和/** ... */是传统的注释实例,它们都是由Java编译器处理过的完全一样,即,它们被忽略(或者更准确:他们被视为空格).

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

这类似于像标签FIXME和TODO:如果你包括像注释// TODO: fix this或者// FIXME: do that,大多数IDE将突出这样的评论,这样你就不会忘记他们.但对于Java来说,它们只是评论.

Answer 3

首先是Javadoc评论.它们可以由javadoc工具处理,以生成类的API文档.第二个是正常的块评论.

Answer 4

阅读JLS的3.7节,可以很好地解释Java中有关注释的所有知识.

评论有两种:

• /*text*/

传统注释:忽略ASCII字符/*到ASCII字符*/的所有文本(如C和C++).

• //文本

行尾注释:忽略从ASCII字符//到行尾的所有文本(如在C++中).

关于你的问题,

第一个

/**
 *
 */

用于声明Javadoc技术.

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

有关Doclet参考API的更多信息.

第二个,如JLS中明确解释的那样,将忽略它们之间的所有文本/*,*/因此用于创建多行注释.

您可能想要了解Java中的注释的其他一些事情

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

因此,以下文字是一个完整的评论:

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

Answer 5

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

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

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

如果你正在编写一个内部API(由同一个程序的不同部分使用的那个),那么Javadoc可能不那么重要了.但是为了维护程序员的利益,你仍然应该为正确的用法或含义不是很明显的任何方法或领域编写Javadoc.

Javadoc的"杀手级功能"是它与Eclipse和其他IDE紧密集成.开发人员只需将鼠标指针悬停在标识符上即可了解他们需要了解的所有内容.不断引用文档成为有经验的Java开发人员的第二天性,这提高了他们自己代码的质量.如果您的API没有使用Javadoc记录,经验丰富的开发人员将不希望使用它.

Answer 6

以下 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.
    }
}

Java 语言支持三种注释：

/* text */

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

/** documentation */

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

// text

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

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

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

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

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