FULL PRODUCT VERSION :
java version "1.5.0_07"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-b03)
Java HotSpot(TM) Client VM (build 1.5.0_07-b03, mixed mode, sharing)

Doesn't matter. Happens in all versions.

ADDITIONAL OS VERSION INFORMATION :
Doesn't matter. Happens in all OS versions

EXTRA RELEVANT SYSTEM CONFIGURATION :
Doesn't matter. Happens in all configurations.

A DESCRIPTION OF THE PROBLEM :
In the javadoc tool, if both a .class and its corresponding .java file are loaded, javadoc uses the one with the latest date. Because a .class file is always compiled from the .java file, the .class file will have a later date and will be the one used by javadoc. This makes sense for javac, but doesn't make sense for javadoc, since the .class file does not contain comments.

In the included example, the comment in Comparable2.java is inherited in the generated Test.html files only when Comparable2.java is newer than Comparable2.class

Desired behavior:
If Javadoc loads both a .java and its corresponding .class file, it should always favor the source file regardless of timestamp, so that it will load the comments.

Effect:
This behavior is a real problem when third parties try to inherit comments from the J2SE. For example, if inheriting the comment from compareTo(T) in Comparable. The user downloads the SCSL src and points the -sourcepath option to it. However, rt.jar file is automatically loaded, and, if it's the same version as the source, probably has a later timestamp on its .class files. Therefore, the .java files are ignored and the comment is not inherited.

NOTE: The current behavior violates the documented behavior, which says:
"The source file for the inherited method need only be on the path specified by -sourcepath for the doc comment to actually be available to copy. "
It makes no mention of a constraint involving timestamps.

I asked Neal Gafter and he confirmed that javadoc probably behaves the same as javac, and agrees that this behavior might not be appropriate for javadoc and should probably be considered a bug.

I don't know of a previous version where Javadoc behaved correctly -- I believe it has always favored the latest file.


STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
CASE A. Run javac and javadoc:

javac *.java
javadoc -d docs -sourcepath . Test.java

Look at docs/Test.html

The generated doc for Test.compareTo(Object) has no inherited comments, because Comparable.class is newer than Comparable.java

CASE B. Then run touch (to update the timestamp) and the same javadoc again:

touch Comparable.java
javadoc -d docs -sourcepath . Test.java

The generated doc for Test.compareTo(Object) *DOES* have inherited comments, because Comparable.java is newer than Comparable.clas


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Expect the generated doc for Test.compareTo(Object) to have inherited comments in either case A or B.
ACTUAL -
CASE A:

compareTo
public int compareTo(java.lang.Object obj)
    Specified by:
        compareTo in interface Comparable2

CASE B:

compareTo
public int compareTo(java.lang.Object obj)
    Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
    Specified by:
        compareTo in interface Comparable2


REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
---------------------- Test.java ------------------------
public class Test implements Comparable2 {
    public int compareTo(Object obj) {
        return 0;
    }
}

------------------ Comparable2.java ---------------
public interface Comparable2<T> {
    /**
     * Compares this object with the specified object for order. Returns a
     * negative integer, zero, or a positive integer as this object is less
     * than, equal to, or greater than the specified object.
     */
    public int compareTo(T o);
}


---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
Workaround is to touch the .java file. This is quite cumbersome (and undocumented).