JDK-6376959 : Algorithm for Inheriting Method Comments seems to go not as documented
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 6
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2006-01-25
  • Updated: 2024-01-22
  • Resolved: 2023-06-28
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 22 Other
22 b05Fixed naResolved
Related Reports
Duplicate :  
Relates :  
Relates :  
Relates :  
Description
The javadoc documentation for what is about the "Algorithm for Inheriting Method Comments" is identical in Mantis, Tiger and Mustang.
References:
    * http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html#inheritingcomments
    * http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/javadoc.html#inheritingcomments
    * http://download.java.net/jdk6/doc/tooldocs/solaris/javadoc.html#inheritingcomments

It says :
"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):
       4.
             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."

With the simple following little Java code, I expect to be in case (1):

--------------------------------
package dummy;
public interface AnInterface {
    /**
     * Method description from AnInterface
     */
    public int whatever();
}
--------------------------------
package dummy;
public class FatherClass
{
    /**
     * Method description from FatherClass
     */
    public int whatever() {
        return 0;
    }
}
--------------------------------
package dummy;
public class SonClass extends FatherClass implements AnInterface
{
    public int whatever() {
        return 1;
    }
}
--------------------------------

I call javadoc that way: "javadoc -d doc -sourcepath src dummy".
The issue is about the method comment for whatever():
- when I use Mantis's javadoc (1.4.2_10), I get "Method description from AnInterface" which is what I expect and what says javadoc documentation.
- when I use Tiger or Mustang javadoc (tried Tiger FCS, Tiger Update 6 and Mustang build 64), I get "Method description from FatherClass" which is not what I expect.

I attached a zip that contains all of it:
    * Java source (src)
    * expected javadoc thanks Mantis (doc-mantis)
    * unexpected javadoc thanks Tiger (doc-tiger)
    * unexpected javadoc thanks Mustang (doc-mustang)

I had a look to http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/index.html but found no documented change that could explain what I get.
I also performed a search into the bug database without finding a duplicate.
Did I miss something ?

Comments
Fix was pushed while main bug was targeted to 21. Resetting the main bug to fixed in 22 and copying the Robo Duke entry here.
28-06-2023

Changeset: 3e0bbd29 Author: Pavel Rappo <prappo@openjdk.org> Date: 2023-06-15 17:47:41 +0000 URL: https://git.openjdk.org/jdk/commit/3e0bbd290c534b0f9729c54cd45308d505907797
28-06-2023

A pull request was submitted for review. URL: https://git.openjdk.org/jdk/pull/14357 Date: 2023-06-07 14:19:16 +0000
07-06-2023

In JDK 11, and current builds of JDK 13 (jdk-13+18, 2019-04-24) the behavior appears to be the same as it was in Tiger (1.5.0, released 2004). That is, if the doc comment on the SonClass method is omitted, the description is copied from FatherClass, preceded by the heading "Description copied from class: FatherClass". If the doc comment consists of "{@inheritDoc}" the description is copied from FatherClass, but there is no "Description copied from class" heading. In either case this seems to be at odds with the comment specification rules, which seem largely unchanged from the quotation in the description. https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html#method-comment-inheritance Since the behavior has been to inherit from superclasses instead of from interfaces for such a long time, perhaps we should consider an alternate path, something like the following. Redefine {@inheritDoc} and missing doc comment to inherit from the superclass hierarchy. Then, add another javadoc tag (or perhaps a parameter to {@inheritDoc} that implements the inherit-from-interfaces behavior. (This seems to be covered by JDK-6934301.) This will avoid breaking any javadoc uses that currently accidentally depend on inheritance from the superclass hierarchy.
08-05-2019

Looks like this is another use case of enhanced @inheritDoc whereby a user can specify from where (source method in the hierarchy) the doc needs to be inherited/copied from.
11-04-2018