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命令将从其重写或实现的方法（如果有）中复制相应的主要描述或标记注释。 / p>

因此，您可以编写：

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

它将从覆盖的方法中复制所有缺少的信息，例如主要描述和v参数的文档。