JDK-6942366 : javadoc no longer inherits doc from sourcepath
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 7
  • Priority: P2
  • Status: Closed
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2010-04-08
  • Updated: 2020-08-31
  • Resolved: 2011-03-08
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 7 Other
7 b121Fixed OpenJDK6Resolved
Related Reports
Relates :  
JDK-6289776 - javadoc should retrieve inherited data from source files even when newer class files found
Description
From Martin Buchholz, ###@###.###

Hi javadoc team,

This is a bug report.  Seems pretty serious - S2?

javadoc man page says,

"""
       The source file for the inherited method need only be on the path spec
       ified by -sourcepath for the doc comment to actually be available to
       copy. Neither the class nor its package needs to be passed in on the
       command line. This contrasts with 1.3.x and earlier releases, where the
       class had to be a documented class
"""

It seems that the jdk has reverted to the 1.3.x behavior.
This happened somewhere between openjdk6-b12 and openjdk6-b13,
and is still broken at head of openjdk7.  But 6u19 works fine!

E.g.

public class JavadocBug {
    public String toString() { return ""; }
}

Then try

javadoc -sourcepath $PATH_TO_JDK_SOURCES/src/share/classes JavadocBug.java

Martin
Comments
EVALUATION Looks like this may have been a long standing bug in javadoc. JavadocClassReader does not force preferSource = true. Therefore, it depends whether the source or class file for the inherited class is newer as to whether or not you get inherited doc comments or not.
20-11-2010
EVALUATION Martin reports: "This happened somewhere between openjdk6-b12 and openjdk6-b13" The primary change in this range was the introduction of docletParentClassLoader.
20-11-2010
EVALUATION Works in b114, with this command: rm -rf play/tmp && /java/re/jdk/7/promoted/all/b114/binaries/linux-amd64/bin/javadoc -d play/tmp -sourcepath /w/jjg/ref/tl/jdk/src/share/classes play/JavadocBug.java && grep Description play/tmp/JavadocBug.html and gets lots of warnings from ct.sym Does /not/ work in b115, with this command, and gets no output from ct.sym rm -rf play/tmp && /java/re/jdk/7/promoted/all/b115/binaries/linux-amd64/bin/javadoc -d play/tmp -sourcepath /w/jjg/ref/tl/jdk/src/share/classes play/JavadocBug.java && grep Description play/tmp/JavadocBug.html
20-11-2010
EVALUATION Fault exists in jdk 7 b118, not in jdk6 b17.
20-11-2010