JavaDoc: inherit method comment from jdk classes?

Question

My goal is to let custom classes inherit method comments from overridden methods of jdk classes. From the doctool documentation, I would assume that the way to go is to set the path to the jdk sources in the -sourcepath option. My problem is that this doesn't seem to work at all - looks like JavaDoc is simply not parsing the JDK source files at all.
The relevant (methinks :) part of the verbose output:
// these are the input options as created by ant run from eclipse under win2k
Executing 'D:\jdk\150_u6\bin\javadoc.exe' with arguments:
'-d'
'D:\JavaWorkspace\harvest\eclipse\javadesktop\jdnc-swingx\dist\javadoc'
'-use'
'-splitindex'
'-verbose'
'-classpath'
'D:\JavaWorkspace\harvest\eclipse\javadesktop\jdnc-swingx\lib\optional\MultipleGradientPaint.jar'
'-sourcepath'
'D:\jdk_doc\srcjdk1.5.0;D:\JavaWorkspace\harvest\eclipse\javadesktop\jdnc-swingx\src\java'
'-link'
'file:D:/jdk_doc/jdk1.5b/docs/api'
'-source'
'1.5'
'org.jdesktop.swingx.table'
The ' characters around the executable and arguments are
not part of the command.
// following is the javadoc output
   [javadoc] [search path for source files: [D:\jdk_doc\srcjdk1.5.0,
D:\JavaWorkspace\harvest\eclipse\javadesktop\jdnc-swingx\src\java]]
   [javadoc] [search path for class files:
[D:\jdk\150_u6\jre\lib\rt.jar, D:\jdk\150_u6\jre\lib\jsse.jar,
D:\jdk\150_u6\jre\lib\jce.jar, D:\jdk\150_u6\jre\lib\charsets.jar,
D:\jdk\150_u6\jre\lib\ext\dnsns.jar,
D:\jdk\150_u6\jre\lib\ext\junit.jar,
D:\jdk\150_u6\jre\lib\ext\localedata.jar,
D:\jdk\150_u6\jre\lib\ext\sunjce_provider.jar,
D:\jdk\150_u6\jre\lib\ext\sunpkcs11.jar,
D:\JavaWorkspace\harvest\eclipse\javadesktop\jdnc-swingx\lib\optional\MultipleGradientPaint.jar]]
   [javadoc] Loading source files for package org.jdesktop.swingx.table...
   [javadoc] [parsing started
D:\JavaWorkspace\harvest\eclipse\javadesktop\jdnc-swingx\src\java\org\jdesktop\swingx\table\ColumnControlButton.java]
..snip..
   [javadoc] Constructing Javadoc information...
   [javadoc] [loading
D:\jdk\150_u6\jre\lib\rt.jar(java/awt/ComponentOrientation.class)]
   [javadoc] [loading
D:\jdk\150_u6\jre\lib\rt.jar(java/awt/Dimension.class)]
   [javadoc] [loading D:\jdk\150_u6\jre\lib\rt.jar(java/awt/Insets.class)]It doesn't seem to matter if javadoc is run from the commandline or through an ant task, the output is basically the same.
The loading from the rt.jar might be the problem, at least when comparing to a report about (maybe exactly the same) problem back in 2004
http://forum.java.sun.com/thread.jspa?forumID=41&threadID=536074
The posters stated that the -sourcepath didn't appear to work under win, while it did work under Solaris. When working, the [loading..] output contained the path to the sources instead of to the classes.
Any help, hint, thought, comment highly welcome!
Thanks in advance
Jeanette

Answer 1

Hi Doug,
thanks for your prompt reply!
My first question is what does the source tree look
below this directory:
-sourcepath 'D:\jdk_doc\srcjdk1.5.0
de]
To work, the the full path to, say, String.java,
would need to be:D:\jdk_docs\srcjdk1.5.0\java\lang\String.java
Because -sourcepath must point to the root of the
source tree. Is this what you have?
exactly, that's the case. In the meantime, I tried to put the sources somewhere relative to the classes (to exlude the possibility that the absolute path poses a problem)I want to document - to no avail.
>
Are you thinking that the class files are loaded from
rt.jar rather than the source .java files from the
source tree?
well, you are the expert to interpret the output :-) All I can be sure of is that this looks similar to output (for windows) in the old forum thread I mentioned and similar to a couple of bug reports. f.i.
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5079630 (which is closed as a duplicate) or
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5105600 which is still open (but probably should be closed - it's a usage error to point to the zipped sources).
Hmm... thinking aloud: comparing my output to the output of the latter (it's quite analogous) it seems that in both cases the sources aren't found .. and the javadoctool falls back to get some search the missing information on the classpath. Maybe the question is: what could possibly go wrong (windows only) to not find the extracted sources (they are definitely there in my context ;-)?
You might try setting -bootclasspath to the empty
string, as describe here:
http://java.sun.com/j2se/javadoc/faq/#bootclasspath
I'll give it a try. BTW, this problem cropped up in the SwingLabs project, we are collectively scratching our heads in:
http://forums.java.net/jive/thread.jspa?threadID=18409
Thanks again!
Jeanette