Java 文档实践:覆盖方法(其返回类型是被覆盖方法的返回类型的子类)

Question

我正在为一个新包编写 Javadoc，我面临着标题中提到的困境。

我将基类方法定义为，

class Vector<E> {
  ..
  public abstract Vector<E> add(Vector<E> v);
  ..
}

重写方法定义为，

class IntVector extends Vector<Integer> {
  ..
  @Override
  public IntVector add(Vector<Integer> v) {
  ..
  }

除了返回类型之外，重写方法不会更改行为。我知道对于重写的方法来说，冗余文档是不可取的。然而在这种情况下，重写方法有自己的文档是有意义的，至少对于返回类型来说是这样。对于这种情况，最佳做法是什么？只需复制规范即可，或者是否有避免重复的好方法？

Answer 1

正如评论中所指出的，如果不同的返回类型没有什么特别之处，而您只想指出它是不同的，那么通常不需要显式地这样做。 javadoc和IDE代码完成将指示返回类型不同。

但是，如果您想添加其他信息，那么您可以查看 method comment inheritance :

When a main description, or @return, @param, or @throws tag is missing from a method comment, the javadoc command copies the corresponding main description or tag comment from the method it overrides or implements (if any).

所以在你的情况下你可以写:

/**
 * @return A verify special IntVector
 */
@Override
public IntVector add(Vector<Integer> v) {
    ...
}

它会复制所有缺失的信息，例如重写方法中 v 参数的主要描述和文档。