JavaDoc: inherit method comment from jdk classes?
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 pathfor source files: [D:\jdk_doc\srcjdk1.5.0,
D:\JavaWorkspace\harvest\eclipse\javadesktop\jdnc-swingx\src\java]]
[javadoc] [search pathforclass 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 filesforpackage 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
[3778 byte] By [
Kleopatraa] at [2007-10-3 5:53:16]
Yes, putting the Java Platform source files on -sourcepath should let you inherit their comments. Your description is very informative, with -verbose and all -- thank you for being so clear. I hadn't heard of it not working on Windows.
My first question is what does the source tree look below this directory:
-sourcepath 'D:\jdk_doc\srcjdk1.5.0
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?
Are you thinking that the class files are loaded from rt.jar rather than the source .java files from the source tree?
You might try setting -bootclasspath to the empty string, as describe here:
http://java.sun.com/j2se/javadoc/faq/#bootclasspath
-Doug
null
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:
>
> [code]
> 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
a quick followup: setting the bootclasspath makes a difference - now the sources are loaded and parsed. Doesn't really solve the problem, though, because it parses _everything_ which blows my local workspace (after many many errors because the sun.* sources are not found ends in an out-of-memory).
While I could give it more memory, I don't think that's a solution ...
Jeanette
Here's another tip that might help. If Javadoc loads both source (.java) and compiled (.class) versions of the same class, it will use the one with the later date. (This is how the compiler is designed, which makes sense for a compiler, but is backwards for javadoc, since normally a compiled file has a later date and it will never find comments in a .class file.)
If the dates of your source files are older than the .class files, then touch the source files to give them the current date and let us know if that makes a difference.
-Doug
Hi Doug,
> Here's another tip that might help. If Javadoc loads
> both source (.java) and compiled (.class) versions of
> the same class, it will use the one with the later
> date. (This is how the compiler is designed, which
> makes sense for a compiler, but is backwards for
> javadoc, since normally a compiled file has a later
> date and it will never find comments in a .class
> file.)
>
> If the dates of your source files are older than the
> .class files, then touch the source files to give
> them the current date and let us know if that makes a
> difference.
>
yeah... it did make the difference, rt.jar has a newer modification date than the extracted sources. After touching the source, it was loaded, parsed and the inherited doc appears.
Touching all sources still blows my local workspace (outofmemory), touching javax.swing only looks okay so far. Shouldn't be too much of a problem, as SwingLabs "official" javadoc is created on a dedicated server (at least that's what I hope) which should be powerful enough.
A typical output snippet - loading from the source if it's newer, loading from the rt.jar otherwise (which holds for inner classes which are often listeners to awtEvents):
[javadoc] [loading D:\jdk\150_u6\jre\lib\rt.jar(javax/swing/JList$3.class)]
[javadoc] [loading D:\jdk\150_u6\jre\lib\rt.jar(javax/swing/DefaultCellEditor$1.class)]
[javadoc] [loading D:\jdk\150_u6\jre\lib\rt.jar(javax/swing/JTabbedPane$ModelListener.class)]
[javadoc] [loading D:\jdk_doc\srcjdk1.5.0\javax\swing\JTabbedPane.java]
[javadoc] [parsing started D:\jdk_doc\srcjdk1.5.0\javax\swing\JTabbedPane.java]
Anyway, I agree with you that the javadoc tools lookup strategy doesn't make much sense - I would consider it a bug.
Thanks a lot for your valuable help!
Jeanette
I'll submit a bug against this. This bug first rose to my consciousness only a couple of weeks ago -- I asked the former Javadoc engineer Neal Gafter about this behavior and he was the one who enlightened me that not only does javadoc behave like javac in regard to timestamps on source and class files, but also that it's a bug.
Doug,> I'll submit a bug against this. good! Could you please post the bug ID here? Then I can add a watch to it to not forget.Thanks againJeanette
I wrote an isolated test case the reproduces the bug and submitted the bug report. Once Sun has reviewed and posted it, I'll find out what the bug ID is and post it here.
Hi Kleopatra,
Here is the bug report I just entered:
Javadoc should use source file rather than more recently modified class file
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6480020
which is a duplicate of a previous bug I was not aware of:
javadoc should retrieve inherited data from source files even when newer class files found
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6289776
-Doug
Doug,I'll add my watches to the bug - thanks again! Jeanette
