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

是正确还是我应该在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