Bug ID: JDK-6289776 javadoc should retrieve inherited data from source files even when newer class files found

Type: Bug
Component: tools
Sub-Component: javadoc(tool)
Affected Version: 5.0,6

Priority: P4
Status: Resolved
Resolution: Not an Issue
OS: generic,windows_xp
CPU: generic,x86

Submitted: 2005-06-23
Updated: 2018-01-17
Resolved: 2018-01-17

I noticed that running javadoc on a set of source files,
which included inherited javadoc from files outside of that set,
silently failed if the referenced classes were available as
class files with newer timestamps than the source files.

But... the .class files don't contain vital information like
@return that is needed in the subclass.

The generated javadoc has silent missing information.  No warning is issued.

###@###.### 2005-06-23 08:27:00 GMT

I revisited this issue and tried to reproduce it, using the following test: ./doit #!/bin/sh -e rm -rf classes out.* $JAVA_HOME/bin/javac p1/*.java -d classes # naturally this one works $JAVA_HOME/bin/javadoc -html5 -sourcepath . Foo.java -d out.1 # works, ie. no warnings, failures, as expected, but incorrectly $JAVA_HOME/bin/javadoc -html5 -classpath classes Foo.java -d out.2 # and this one also works $JAVA_HOME/bin/javadoc -html5 -classpath classes -sourcepath . Foo.java -d out.3 ./Foo.java import p1.*; public class Foo extends Bar { /** {@inheritDoc} */ public boolean isBar() { return false; } } ./p1/Bar.java package p1; /** A heavy meal. */ public class Bar { /** * Returns true if it is a bar. * @return true if bar. */ public boolean isBar() { return true; } } Inspecting the source code, javadoc correctly indicates to javac that source is prefered. http://hg.openjdk.java.net/jdk/jdk/file/7067fe4e054e/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocClassFinder.java#l73 I am concluding, this has been resolved via JDK-6942366, I am closing it as NAI, if this is still an issue pelase reopen or file a new issue.

17-01-2018

EVALUATION The problem, and fix, should be much the same as for this apt bug fix: 4993280: apt should favor source files over class files for type information ###@###.### 2005-07-19 01:40:38 GMT

19-07-2005

WORK AROUND The workaround is to run javadoc without rt.jar on the -bootclasspath In perl, include the obvious places in the j2se workspace on the -sourcepath, and use a -bootclasspath with rt.jar explicitly removed (from my ws-doc script). my $variant = j2seVariant; my $winsol = ($^O =~ /^(?:Windows|cygwin)/ ? "windows" : "solaris"); "javadoc", "-sourcepath", join(':', ("$ws/src/share/classes", "$ws/build/$variant/gensrc", "$ws/src/$winsol/classes")), "-bootclasspath", join(':', grep {/(?<!\brt)\.jar$/} DirFiles("$ws/build/$variant/lib")), See /home/mb29450/bin/sun/ws-doc. ###@###.### 2005-06-23 08:27:00 GMT

23-06-2005

Duplicate :	JDK-6480020 - Javadoc should use source file rather than more recently modified class file
Duplicate :	JDK-6293091 - REGRESSION: Inheriting comments from J2SE does NOT work.
Relates :	JDK-4993280 - apt should favor source files over class files for type information
Relates :	JDK-6942366 - javadoc no longer inherits doc from sourcepath