用于重写方法的Java文档实践,其返回类型是重写方法的返回类型的子类

问题描述 投票:0回答:1

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

我有基类方法定义为,

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

最重要的方法定义为,

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

覆盖方法不会更改除返回类型之外的行为。我知道重写文档不适用于重写方法。但是在这种情况下,重写方法有自己的文档是有意义的,至少对于返回类型。这种情况的最佳做法是什么?只需复制规范或是否有避免重复的好方法?

java javadoc code-documentation
1个回答
1
投票

正如评论中所指出的,如果不同的返回类型没有什么特别的,你只想指出它是不同的,那么通常没有必要明确地这样做。 javadoc和IDE代码完成将指示返回类型不同。

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

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

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

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

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