Question

我在java中编写了一个界面，我想知道是否应该在界面方法的javadoc评论中添加标签（@ param，@ return等）或者如果我只应该在实施类中包含这些标签＆＃39;方法的javadoc评论。这是一个例子：

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

那么javadoc评论应该是这样吗？

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注释中？

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注释，并包含参数，因为它们很重要！

Javadoc注释应该确定“契约”是什么，你希望实现接口的类满足，参数和返回是这个合同的重要部分。

这是任何实现你的界面的人都有关于他们应该怎么做的信息。

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

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

Oracle在此处提供了一个优秀的，相对可读且全面的Javadoc评论指南：

How to Write Doc Comments for the Javadoc Tool

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

1 个答案: