JavaDoc接口注释

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();
}

这是对的吗？还是我应该在课堂评论中添加其他内容？

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