United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4857717 : "Specified by:" and "Overrides:" should exist & point to ext. referenced classes

Details
Type:
Bug
Submit Date:
2003-05-02
Status:
Resolved
Updated Date:
2014-05-05
Project Name:
JDK
Resolved Date:
2003-09-26
Component:
tools
OS:
windows_2000
Sub-Component:
javadoc(tool)
CPU:
x86
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.2
Fixed Versions:
5.0 (tiger)

Related Reports
Duplicate:

Sub Tasks

Description
[This bug is re-written from bug 4854934]

It appears that when method A.m overrides method in external referenced class B,
the "Overrides:" section is not generated (but should be).  That is, if B is not
passed in on the command line, javadoc does not create the "Overrides:" section
for method m.  If B is passed in, then it does create the "Overrides:" section.

Example:  Given this source file with method read() that overrides 
"public int read()" in FilterReader:

---------------- XReader.java ---------------------
public class XReader extends java.io.FilterReader {
  /** 
   * This is a doc comment
   */
   public int read() {
      return 'W';
   }
}
---------------------------------------------------

Generate the HTML documentation using Javadoc 1.4.2-beta:

javadoc -d html XReader.java

The generated HTML documentation for XReader.read() 
is missing any "Overrides:" labels.  It actually looks
like this:

-----------------------------
read

public int read()

   This is a doc comment
------------------------------

It should instead look like this, with override labels:

-----------------------------
read

public int read()

   This is a doc comment

Overrides:
   read in class FilterReader
   ~~~~          ~~~~~~~~~~~~
------------------------------

Adding the -link or -linkoffline option makes no difference -- 
the labels and links still do not appear when trying this:

javadoc -d html -linkoffline "http://java.sun.com/j2se/1.4/docs/api" . XReader.java

In this case, "read" should be a link to java/io/FilterReader.html#read()
and "FilterReader" should be a link to java/io/FilterReader.html,
identical to this J2SE class that extends FilterReader:

http://java.sun.com/j2se/1.4.1/docs/api/java/io/PushbackReader.html#read()

The presence of these labels and links should be independent
of inheriting doc comments.

FWIW, I tested for the presenece of "Specified by:" when implementing
an external referenced class (to see if it's a problem), and it works 
just fine, producing "Specified by:" labels and links.  Here's that source 
file:

----------------- XComparable.java -----------------------
public class XComparable implements java.lang.Comparable {
   public int compareTo(Object o) {
      return 'W';
   }
}
--------------------------------------------------------

                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger

FIXED IN:
tiger

INTEGRATED IN:
tiger
tiger-b22


                                     
2004-06-14
PUBLIC COMMENTS

We have fixed this bug for the 1.5 release.  I agree that it is incorrect for the doclet to skip "overrides" or "implemented" documentation just because the method being overriden or implemented is external. 
###@###.### 2003-05-03
                                     
2003-05-03
EVALUATION

Accepted.
###@###.### 2003-05-02

There is really nothing to fix.  I can reproduce this bug in the pre-toolkit standard doclet but not in the toolkit standard doclet.  This code to insert the "overriden" or "implements" documentation is included in the toolkit so it will be fixed in every doclet that uses it.

I will mark this bug as fixed when we actually get to check the toolkit into the TL workspace. 
###@###.### 2003-05-03
                                     
2003-05-03



Hardware and Software, Engineered to Work Together