JavaDoc 接口注释 [关闭]答案

【问题标题】：JavaDoc Interface comments [closed]JavaDoc 接口注释 [关闭]
【发布时间】：2012-03-03 07:45:20
【问题描述】：

我有一个接口 A，它有方法 x、y 和 z。我是这样评论课程的：

/**
 * 
 * A.java
 * Interface class that has the following methods.
 * 
 * @author MyName
 * @since mm-dd-yyyy
 */

public interface A {

    //method description for x
    void x();

    //method description for y
    void y();

    //method description for z
    void z();
}

这是正确的还是我应该在 CLASS COMMENTS 中添加其他内容？

【问题讨论】：

你为什么不接受 Jon Skeet？

标签： java interface comments javadoc

【解决方案1】：

是的，您应该为您的接口编写适当的 Javadoc cmets，以明确说明接口背后的动机以及调用者和实现者的约定。

以JDK代码中的一些接口为例，例如java.util.List

【讨论】：

【解决方案2】：

不，您没有为这些方法指定任何 JavaDoc cmets。使用或实现接口的人如何知道这些方法的用途是什么？您应该使用正确的 JavaDoc 描述：

/**
 * This method fromulgates the wibble-wrangler. It should not be called without
 * first saturating all glashnashers.
 */
void x();

请记住，与大多数针对调用者的 JavaDoc 不同，接口文档有两种受众：调用者和实现者。您需要清楚双方双方可以期待什么以及他们应该如何行事。是的，这很难做好:(

编辑：就顶级 cmets 而言：

就我个人而言，我会去掉@author 标签，因为它在IMO 很少有用。（通常查看源代码管理更合适...）
除非您实际上有一个有意义的版本控制策略（不仅仅是日期），否则我会去掉 @since 标签。
说明源文件没有意义
“具有以下方法的接口类”的描述毫无意义并且自相矛盾（因为接口不是类）。正在阅读 JavaDoc 的人已经能够看到方法列表。您应该尝试在此处提供额外信息。

就像普通的类文档一样，接口文档应该说明类型的用途——它在更宏大的方案中的作用，也许是一个预期如何使用它的示例，等等。查看 JDK 中的示例以了解一般情况-合理的JavaDoc。

【讨论】：

我不是在问方法 cmets，我问的是类 commetn。我知道如何评论我只不确定接口类的方法
@user1181847：好吧，如果你举一个没有记录方法的例子，然后问你是否做对了，你期望什么？
我在问我是否在课堂评论中做得对。我已经在我的问题中指定了
实际上，当我使用与网站上记录的最新版本不同的版本的库时，我讨厌它，并且没有任何版本标签来指示该方法是否已经永远存在。（当然，这意味着如果您正在编写和发布库，则应该制定版本控制政策。）或者，将 Javadoc 用于库的所有版本在您的网站上.
@PaŭloEbermann：是的，如果你要正确地进行版本控制，然后记录它 - 但只是输入日期很少有用，IMO ......特别是如果你随后向界面添加方法而不注意到它......