Community
Participate
Working Groups
Currently if a jar file has a source and Javadoc attached to it, the source will always win when Eclipse displays the Javadocs. It would appear at first sight to be more advantageous (processor wise) to use already generated Javadocs instead of generating new ones every time. It would be good to be able to set the precedence in the config. It would be hard to imagine a situation where the source would be more up-to-date, especially given that many projects build their Javadocs from an external source, not the Java source (c.f. SleepyCat's Berkeley Database), so the source may not even contain the correct documentation.
I assume this is when showing a hover.
For all of hover, Javadoc window and shift+F2 to open in external browser.
This is like that for two reasons: 1) history: earlier versions were not able to extract Javadoc from attached Javadoc. 2) performance: in the default JRE install/setup we have the source attached from a local file and an external URL for the Javadoc. Hence changing the default would impact performance. I would not want to change the current default but maybe we could add a preference to the 'Javadoc Locations' property page. Olivier, Martin: what do you guys think?
>For all of hover, Javadoc window and shift+F2 to open in external browser. Shift+F2 does not use the source.
If there is an attached source and an attached Javadoc... does that not already imply that the user has requested to use the attached Javadoc over the source? If the user attaches a Javadoc, I would suggest that it is used. If there are performance issues related to this, then perhaps a note in the Javadoc panel could suggest that attaching source already accomplishes the task of providing Javadocs and only to attach Javadocs if there is no source available, or if the Javadocs in the source are not appropriate.
I agree if this is non-standerd JAR but when it comes to the JDK then this is automatically setup for the user.
(In reply to comment #6) > I agree if this is non-standerd JAR but when it comes to the JDK then this is > automatically setup for the user. OK, I see... because the default setup would then involve URL lookups to the SUN Javadocs on their website. (I actually changed this to the Javadoc documentation zipfile because that was happening anyway for me... OS X doesn't come with Java's source). In that case, would it not be sensible to favour Javadocs in the following order:- - attached Javadoc archive - extract from attached source - attached Javadoc URL and if you want to cover all scenarios, provide an option to allow the Javadoc URL to override the source (perhaps sensible if the URL is actually a local directory). Although, I personally have no need for such an option.
(In reply to comment #7) > - attached Javadoc archive > - extract from attached source > - attached Javadoc URL actually, a much more sensible ordering would be - attached Javadoc local URL or archive - extract from attached source - attached Javadoc external URL not sure how practical it would be for you guys to implement, but it would certainly cover all the scenarios we've discussed.
Changing OS from Mac OS to Mac OS X as per bug 185991
Now it doesn't even fall back to attached javadoc if a source without any docs is set. Such a scenario isn't as uncommon as it might sound. E.g., if I decompile a bunch of class files (for which I have javadoc-html-files) to get some rudimentary source code then the resulting java files will not have any javadocs. So I have to keep attaching and removing the source files whenever I want to switch between looking at the source and looking at the javadocs. (This is every bit as annoying as it sounds.)
>Now it doesn't even fall back to attached javadoc if a source without any docs >is set. Not true. This did not change. If you can reproduce then please file a new bug for that with steps to reproduce.
*** Bug 336306 has been marked as a duplicate of this bug. ***
(In reply to comment #3) > I would not want to change the current default but maybe we could add a > preference to the 'Javadoc Locations' property page. +1 for an option 'Prefer attached Javadoc over attached source'. That way, we could even fall back to showing Javadoc from attached source if the attached Javadoc doesn't contain actual doc. The implementation needs more (or extended) API from JDT/Core: - IJavaElement#getAttachedJavadoc(IProgressMonitor) currently always returns null for source elements - IClasspathAttribute needs a new constant for the option
> The implementation needs more (or extended) API from JDT/Core: See bug 336334.
I observe same behavior as was reported by Marcus in 2009 earlier in this report. I documented in (the now duplicate) bug: 336306. If decompiled source is attached (happens by default with m2e maven plugin) the java docs are ignored for the hover and javadoc window. Very inconvenient. Thanks for looking into it
Created attachment 188440 [details] Patch v0.1 I've started to look into this, but it's more work than it appeared on first sight. The attached patch implements parts of the UI to configure Javadoc attachments, but it needs a lot more work: - The new attribute needs to be considered everywhere we deal with Javadoc attachments. - Need code that reads and saves the classpath modifications - for Jars directly on the classpath - for user libraries - for classpath containers - For classpath containers, this also affects contributed containers like the JRE System Library, etc. This needs more API in jdt.ui (BuildPathDialogAccess, ...) and adoption in jdt.launching (LibraryLocation, ...) and jdt.debug.ui (VMLibraryBlock, ...).
*** Bug 366811 has been marked as a duplicate of this bug. ***
