-
Bug
-
Resolution: Fixed
-
P3
-
6
-
b05
-
generic
-
generic
Issue | Fix Version | Assignee | Priority | Status | Resolution | Resolved In Build |
---|---|---|---|---|---|---|
JDK-8310166 | na | Pavel Rappo | P3 | Closed | Not an Issue |
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 ?
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 ?
- backported by
-
JDK-8310166 Algorithm for Inheriting Method Comments seems to go not as documented
- Closed
- duplicates
-
JDK-8144034 "Automatic Copying of Method Comments" doesn't always give preference to interfaces over superclasses
- Closed
- relates to
-
JDK-6934301 Support directed inheriting of class comments with @inheritDoc
- Resolved
-
JDK-8285368 Overhaul doc-comment inheritance
- Resolved
-
JDK-6369229 For several methods, the javadoc body comes from the ancestor in place of from the interface
- Closed
(2 links to)