Java 中的内联注释： /** 反对 /*？答案

【问题标题】：Inline comments in Java: /** opposed to /*?Java 中的内联注释： /** 反对 /*？
【发布时间】：2012-01-22 23:58:16
【问题描述】：

我是否有理由更喜欢在 java 中这样编写 inline-cmets：

/** Init operation */
mindControlLaser.engage();

而不是只使用一个 *:

/* i'm a happy comment */

Eclipse 对语法进行不同的着色，但“工具链”（javadoc、eclipse 等）中真的有任何东西在使用 /** */ 时给我带来优势吗？

【问题讨论】：

【解决方案1】：

没有理由使用内联 cmets。

/** 向 javadoc 实用程序发出信号，以自动提取有关 API 的文档。在方法内部使用时没有任何作用。

【讨论】：

【解决方案2】：

常规 cmets

/* Regular comment */

使用常规 cmets，您可能会解释一个棘手的算法的一部分。或者您不想成为 JavaDOC 一部分的任何内容。内联 cmets 也是常规 cmets，可以在描述较短的情况下使用。

/** JAVA DOC COMMENT */

使用 javadoc，您可以解释类、方法或字段（变量）。

然后，像 Eclipse 这样的大多数 IDE 可以在您编写代码时使用这些信息来帮助您。例如，如果您有一个classA 和一个classB，并且在classB 中使用来自classA 的内容，那么如果您将鼠标悬停在方法或变量上，您可以看到JavaDOC 信息。非常方便。

此外，使用ant 之类的构建工具，您可以自动从JavaDOC 构建HTML 文件，并且如果您发布它们，您可以允许其他人重用您的工作。例如查看 Java 本身的文档here。

【讨论】：

【解决方案3】：

评论的语法是/* */。

Javadoc 默认使用/** */。这是一条注释，因为第二个 * 在注释内，因此编译器不会有不同的看法。

因此，如果没有第二个 *，您只是添加了一条评论，而使用第二个您编写 javadoc：当您将鼠标悬停在其他地方的函数调用上时，eclipse 会识别它并为您提供提示等。

【讨论】：

【解决方案4】：

/** .... */ 会生成 Javadoc，/* ... */ 不会。

当然，它会在正确的地方生成Javadoc。 Javadoc 也有一个非常明确的格式，请参阅here。

【讨论】：

【解决方案5】：

/** 表示“文档”cmets； Javadocs 等在为您的代码创建文档时查找这些。

所以它们真的应该只用在方法和类上面，例如：

/**
 * Class to represent tigers.
 */
class Tiger {
    /**
     * Go extinct.
     */
    void goExtinct() {
    }
}

/* 变体仅表示标准注释块。

【讨论】：

【解决方案6】：

是的，使用/** Primary sentence. Other descriptions... */ 是javadoc 表示法。 . 之前的第一句将用于 javadoc 的摘要，其余的将用于详细视图。

【讨论】：

【解决方案7】：

Javadoc 对 /** 的处理方式不同；上面有 /** cmets 的类和方法将被放入 javadoc 输出。

【讨论】：