Java Documentation Override Method does not InheritDoc

Question

A method that overrides another method does not inherit documentation of the method it is overriding. Is there any way to explicitly tell it to inherit the documentation?

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

Answer 1

According to the javadoc documentation:

Inheriting of comments occurs in all three possible cases of inheritance from classes and interfaces:

• When a method in a class overrides a method in a superclass
• When a method in an interface overrides a method in a superinterface
• When a method in a class implements a method in an interface

Comments can be explicitly inherited using the {@inheritDoc} tag. If no comments are provided for an overriding method, comments will be implicitly inherited. Aspects of the inheriting comments (e.g. params, return value, etc.) can be overridden if you so desire.

Importantly, you need to make sure that the source file containing the code with the comment to be inherited is available to the javadoc tool. You can do this by using the -sourcepath option.

Answer 2

From the 1.4.2 Javadoc manual

Algorithm for Inheriting Method Comments - If a method does not have a doc comment, or has an {@inheritDoc} tag, the Javadoc tool searches for an applicable comment using the following algorithm, which is designed to find the most specific applicable doc comment, giving preference to interfaces over superclasses:

1. Look in each directly implemented (or extended) interface in the order they appear following the word implements (or extends) in the method declaration. Use the first doc comment found for this method.
2. If step 1 failed to find a doc comment, recursively apply this entire algorithm to each directly implemented (or extended) interface, in the same order they were examined in step 1.
3. If step 2 failed to find a doc comment and this is a class other than Object (not an interface): 1. If the superclass has a doc comment for this method, use it. 2. If step 3a failed to find a doc comment, recursively apply this entire algorithm to the superclass.

I believe (though I could be wrong) that this basic algorithm still applies to Java 1.5 and 1.6... though it really would be awfully nice of Sun to publish a complete self-contained definitive document for each version of the toolset... I guess it's an overhead they just can't afford, atleast for a free toolset.

Cheers. Keith.

---

Edit:

Here's a quick and dirty example.

Code

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...

Produces 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