覆盖方法的 Java 文档实践，其返回类型是被覆盖方法的返回类型的子类答案

【问题标题】：Java documentation practice for overriding methods whose return type is subclass of overridden method's return type覆盖方法的 Java 文档实践，其返回类型是被覆盖方法的返回类型的子类
【发布时间】：2019-04-29 17:53:56
【问题描述】：

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

我将基类方法定义为，

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

重写方法定义为，

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

覆盖方法不会改变除了返回类型之外的行为。我知道冗余文档对于被覆盖的方法是不可取的。但是在这种情况下，覆盖方法拥有自己的文档是有意义的，至少对于返回类型是这样。这种情况的最佳做法是什么？只是复制规范还是有避免重复的好方法？

【问题讨论】：

你有什么要说的吗？ “返回一个 IntVector”？除了返回类型的声明之外，这真的值得一提吗？
我希望用户知道 IntVector.add(v) 的返回类型是 IntVector，以便他们可以使用 IntVector 作为返回值。
如果用户使用的是IntVector，那么他们的IDE会告诉他们返回类型是IntVector。

标签： java javadoc code-documentation

【解决方案1】：

正如 cmets 中所指出的，如果不同的返回类型没有什么特别之处，而您只想指出它是不同的，那么通常不需要显式执行此操作。 javadoc和IDE代码补全会提示返回类型不同。

不过，如果你想补充更多信息，那么你可以看看method comment inheritance：

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

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

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

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

【讨论】：

感谢您的回答！您能否详细说明“javadoc和IDE代码完成将指示返回类型不同”，javadoc部分？现在（重写方法中没有注释）用户在“基类中声明的方法”中看到 add() 方法，这表明返回类型是 Vector。
我无法重现您所描述的内容。当我运行 javadoc -sourcepath src -d docs -subpackages my（在 Java 8 和 12 中）时，我看到“方法摘要”下列出了被覆盖的方法，即使返回类型没有改变（不确定这是否是有意的）。但是，对我来说，“声明的方法”部分（Java SE 12 文档也使用）称为“方法继承自”（就像 Java SE 8 文档的情况一样）。
@user1200373，你用--overridden-methods=summary吗？如果是这样，那么您很可能遇到JDK-8219147。
你说的很对，--overridden-methods=summary是用的；当我仅使用 @inheritDoc 标记时，您提到的错误会阻止为覆盖方法生成 javadoc。该错误还为我提供了 JDK 库中类似情况的示例，这就是我将遵循的约定。
附带说明 - 我观察到的 --overridden-methods=summary 生成“方法声明在”部分，而 --overridden-methods=detail 生成“方法继承自”部分。