用于重写方法的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：

当方法注释中缺少主要描述或@return，@ param或@throws标记时，javadoc命令会从其覆盖或实现的方法（如果有）复制相应的主要描述或标记注释。

所以在你的情况下，你可以写：

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

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