JavaDoc：在哪里向文档添加注释/备注？答案

【问题标题】：JavaDoc: where to add notes/remarks to documentation?JavaDoc：在哪里向文档添加注释/备注？
【发布时间】：2011-08-02 22:30:40
【问题描述】：

在使用 C# 编码时，我总是发现标签 remarks 对于提供有关类或方法的实现的注释或提供有关我正在实现的理论的信息非常有用。我现在正在使用 Java，但找不到合适的 JavaDoc 标记。也许在 Java 中你以不同的方式完成此任务，有人知道吗？

【问题讨论】：

标签： java coding-style javadoc

【解决方案1】：

据我所知，没有用于注释或备注的专用 Javadoc 标记。一般来说，Javadoc 的第一句话应该对类/方法/字段进行简要说明。然后应遵循完整的描述。如果你想包含任何注释，一个带有“注释：”的专门段落就足够了。

/**
 * Brief description. Full description of the method, generally without
 * implementation details.
 * <p>
 * Note: Additional information, e.g. your implementation notes or remarks.
 * </p>
 * @param input description of the parameter
 * @return description of return value
 * 
 * @since version
 * @author name of the author
 */
public boolean doSomething(String input)
{
    // your code
}

【讨论】：

一般来说，如果你打开（xml-）标签，你应该在某个地方关闭它们。
This answer 现在应该被认为是正确的。

【解决方案2】：

随着 Java 编程语言的第 8 次迭代，最终为开发人员提供了三个可在其代码文档中使用的附加标签，它们应该可以满足您的需求：@apiNote、@implSpec 和 @implNote（参见，例如，更详细的讨论：blog.codefx.org/java/new-javadoc-tags/)。

【讨论】：

在你的答案中直接解释这些标签的用例会很好（它们之间有什么区别）。

【解决方案3】：

您也可以创建自己的自定义标签。

这是一个包含自定义标签“@note”的 javadoc 注释：

    /**
     * Quark represents a quark.
     *
     * @note If you spin a quark, it will spin forever!
     */
    public class Quark {

    }

要为上述生成 javadoc，请像这样运行 javadoc：

javadoc -tag note:a:"Note:" Quark.java

来源：http://www.developer.com/java/other/article.php/3085991/Javadoc-Programming.htm

【讨论】：

【解决方案4】：

如果您认为实现细节足以成为 Javadoc 的一部分，您应该在 Javadoc 注释本身的一个段落中提供它们：

/**
 * Does something.
 * <p>
 * <b>Implementation details:</b><br />
 * Blah blah blah...
 * </p>
 */
public void doSomething() {
    // ...
}

【讨论】：