java - Java 文档覆盖方法不 InheritDoc

Question

覆盖另一个方法的方法不会继承它所覆盖的方法的文档。有没有办法明确告诉它继承文档？

/**
  * {@inheritDoc}
  * 
  * This implementation uses a dynamic programming approach.
  */
@Override
public int[] a(int b) {
    return null;
}

Answer 1

根据javadoc 文档：

注释的继承发生在从类和接口继承的所有三种可能的情况下：

• 当类中的方法覆盖超类中的方法时
• 当接口中的方法覆盖超接口中的方法时
• 当类中的方法实现接口中的方法时

可以使用{@inheritDoc}标记显式继承注释。如果没有为覆盖方法提供注释，则注释将被隐式继承。如果您愿意，可以覆盖继承注释的各个方面（例如参数、返回值等）。

重要的是，您需要确保包含要继承的注释的代码的源文件可用于 javadoc 工具。您可以使用-sourcepath选项来执行此操作。

Answer 2

来自1.4.2 Javadoc 手册

继承方法注释的算法 - 如果方法没有 doc 注释，或有 {@inheritDoc} 标记，Javadoc 工具使用以下算法搜索适用的注释，该算法旨在找到最具体的适用的 doc 注释，优先于接口而不是超类：

1. 按照方法声明中实现（或扩展）一词后出现的顺序查看每个直接实现（或扩展）的接口。使用为此方法找到的第一个文档注释。
2. 如果步骤 1 未能找到文档注释，则递归地将整个算法应用于每个直接实现（或扩展）的接口，按照在步骤 1 中检查它们的相同顺序。
3. 如果第 2 步未能找到文档注释，并且这是 Object 以外的类（不是接口）： 1. 如果超类有此方法的文档注释，请使用它。2. 如果步骤 3a 未能找到文档注释，则递归地将整个算法应用于超类。

我相信（尽管我可能是错的）这个基本算法仍然适用于 Java 1.5 和 1.6……尽管 Sun 为工具集的每个版本发布一个完整的自包含的权威文档真的会非常好……我想这是他们无法承受的开销，至少对于免费工具集而言。

干杯。基思。

---

编辑：

这是一个快速而肮脏的例子。

代码

package forums;


interface Methodical
{
  /**
   * A no-op. Returns null.
   * @param i int has no effect.
   * @return int[] null.
   */
  public int[] function(int i);
}


interface Methodological extends Methodical
{
  /**
   * Another no-op. Does nothing.
   */
  public void procedure();
}


class Parent implements Methodological
{
  @Override
  public int[] function(int i) {
    return null;
  }

  @Override
  public void procedure() {
    // do nothing
  }

}


class Child extends Parent
{
  /** {@inheritDoc} */
  @Override
  public int[] function(int i) {
      return new int[0];
  }

  /** {@inheritDoc} */
  @Override
  public void procedure() {
    System.out.println("I'm a No-op!");
  }

}


public class JavaDocTest
{
  public static void main(String[] args) {
    try {
      new Child().procedure();
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Javadoc

C:\Java\home\src\forums>javadoc -package -sourcepath . JavaDocTest.java
Loading source file JavaDocTest.java...
Constructing Javadoc information...
Standard Doclet version 1.6.0_12
Building tree for all the packages and classes...
Generating forums/\Child.html...
Generating forums/\JavaDocTest.html...
Generating forums/\Methodical.html...
Generating forums/\Methodological.html...
Generating forums/\Parent.html...
Generating forums/\package-frame.html...
Generating forums/\package-summary.html...
Generating forums/\package-tree.html...
Generating constant-values.html...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...
Generating stylesheet.css...

产生file:///C:/Java/home/src/forums/index.html

function

public int[] function(int i)

    A no-op. Returns null.

    Specified by:
        function in interface Methodical
    Overrides:
        function in class Parent

    Parameters:
        i - int has no effect. 
    Returns:
        int[] null.

procedure

public void procedure()

    Another no-op. Does nothing.

    Specified by:
        procedure in interface Methodological
    Overrides:
        procedure in class Parent

Answer 3

将 @Override 与 javaDoc 交换。

    @Override
    /**
     * {@inheritDoc}
     */