Java 文档覆盖方法不继承文档

eclipse java documentation inheritdoc

2022-09-03 01:03:50

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

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

答案 1

根据javadoc文档：

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

当类中的方法重写超类中的方法时

当接口中的方法覆盖超接口中的方法时

当类中的方法在接口中实现方法时

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

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

答案 2

来自 1.4.2 Javadoc 手册

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

在每个直接实现（或扩展）的接口中，按照它们在方法声明中单词实现（或扩展）之后出现的顺序进行查看。使用为此方法找到的第一个文档注释。

如果步骤 1 未能找到文档注释，请以递归方式将此整个算法应用于每个直接实现（或扩展）的接口，其顺序与步骤 1 中检查的顺序相同。

如果步骤 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