Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-6376959

Algorithm for Inheriting Method Comments seems to go not as documented

    XMLWordPrintable

Details

    • b05
    • generic
    • generic

    Backports

      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 ?

        Attachments

          Issue Links

            Activity

              People

                prappo Pavel Rappo
                yjoan Yves Joan (Inactive)
                Votes:
                0 Vote for this issue
                Watchers:
                7 Start watching this issue

                Dates

                  Created:
                  Updated:
                  Resolved:
                  Imported:
                  Indexed: