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手册

用于继承方法注释的算法 - 如果方法没有文档注释或具有{@inheritDoc}标记,则Javadoc工具使用以下算法搜索适用的注释,该算法旨在查找最具体的适用文档注释,优先考虑超类上的接口:

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

我相信(尽管我可能错了)这个基本算法仍然适用于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