接口方法的javadoc注释中的标签？

Question

我正在用 java 编写一个接口，我想知道是否应该在接口的方法的 javadoc cmets（@param、@return 等）中包含标签，或者我是否应该只在实现类中包含这些标签'方法的 javadoc cmets。这是一个例子：

我有一个ShapeInterface接口，并且有形状的实现类（圆形、三角形等）

那么javadoc cmets应该是这样的吗？

public interface ShapeInterface{

/**
 * Sets the x-coordinate for this shape
 * @param x the x-coordinate for this shape
 */
public void setX(int x);

/**
 * Gets the x-coordinate of this shape
 * @return this.x the x-coordinate of this shape
 */
public int getX();
}

或者它们应该如下所示，标签只出现在实现类方法的 javadoc cmets 中？

public interface ShapeInterface{

/**
 * Sets the x-coordinate for this shape
 */
public void setX(int x);

/**
 * Gets the x-coordinate of this shape
 *
public int getX();
}

谢谢

Answer 1

您应该在所有接口上编写 Javadoc cmets 并包含参数，因为它们很重要！

Javadoc cmets 应该建立您希望实现接口的类满足的“约定”，并且参数和返回是该约定的重要部分。

任何实现你的接口的人都可以通过这种方式获得有关他们应该如何去做的信息。

请注意，在记录无法知道实现类的确切操作的接口方法时，您可能必须避免过于具体。

如果您有任何疑问，请参阅 Oracle 类的官方 Javadocs，例如 List 接口：http://docs.oracle.com/javase/7/docs/api/java/util/List.html#remove(java.lang.Object)

Oracle 在这里有一个优秀的、相对易读的和全面的 Javadoc cmets 指南：

How to Write Doc Comments for the Javadoc Tool