Question

我有一个接口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评论中添加其他内容吗？

Answer 1

不，您尚未为方法指定任何JavaDoc注释。如何使用或实现界面意味着知道这些方法的用途？您应该使用正确的JavaDoc描述：

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

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

编辑：就顶级评论而言：

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

就像普通的类文档一样，接口文档应该说明类型的目的 - 它在更宏大的方案中的作用，也许是一个如何使用它的例子等等。查看JDK中的示例 - 合理的JavaDoc。

Answer 2

是的，您应该为您的界面编写适当的Javadoc注释，以明确说明界面背后的动机以及合同对调用者和实现者的影响。

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

JavaDoc接口注释

2 个答案: