Java文档重写方法不会继承注释。

Question

覆盖另一个方法的方法不会继承被覆盖的方法的文档。是否有任何方法可以明确告诉它继承文档？

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

- Verhogen

Answer 1

根据javadoc文档：

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

• 当类中的一个方法覆盖父类中的方法时
• 当接口中的一个方法覆盖超级接口中的方法时
• 当类中的一个方法实现接口中的一个方法时

可以使用{@inheritDoc}标记来显式继承注释。如果没有提供覆盖方法的注释，则将隐式继承注释。如果需要，可以覆盖继承注释的某些方面（例如参数、返回值等）。

重要的是确保包含带有要继承注释的代码的源文件对javadoc工具可用。可以使用-sourcepath选项来实现这一点。

- Brandon E Taylor

Answer 2

来自1.4.2 Javadoc手册

继承方法注释的算法 - 如果一个方法没有文档注释，或者有一个{@inheritDoc}标签，则Javadoc工具使用以下算法搜索适用的注释，该算法旨在找到最具体的适用的文档注释，并优先考虑接口而不是超类：

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

我相信（尽管我可能错了），这个基本算法仍适用于Java 1.5和1.6...尽管Sun真的很好，可以为每个版本的工具集发布完整的自包含的确定性文档...我猜这是他们无法承受的开销，至少对于一个免费的工具集来说。

干杯。 Keith。

---

编辑：

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

代码

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

- corlettk

---

我在帖子中引用的javadoc文档是针对J2SE 1.6版本的。 - Brandon E Taylor

Answer 3

将 @Override 替换为 javaDoc。

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

- user1648825

---

那完全没有任何影响。 - Bex