Javadoc not correctly shown

[4javier]

Spring Tool Suite 4
Version: 4.6.0.RELEASE
Build Id: 202003181317

OpenJDK-11
Arch Linux

Documentation for Java library get shown only in browser. Hovering pop-up and Javadoc view show the message

Note: This element has no attached source and the Javadoc could not be found in the attached Javadoc.

I set java-11-openjdk as Jre, and tried both with online documentation, both with local archive. Same behaviour.
I'm testing on a clean workspace.
For spring-starter-project, Spring-libs documentation gets correctly shown in pop-up and javadoc view.
I manage my project by Gradle, that I think attaches source instead of Javadoc to external libraries.
The image shows a test done passing the docs dir created by the official package of my distro as URI. You can see how internal browser find the correct page, while javadoc view print the error message.
Identical situation with online URL, and local compressed archive too.
I managed to make it show javadoc only attaching the source archive to the library.

[kdvolder]

This works fine for me.

It is probably because you don't have the source code installed for your jre/jdk. Or if you do, then somehow Eclipse may not know where to find it.

Eclipse (a bit surprising to most people) doesn't actually show javadoc by looking for javadocs from html files, but instead extracts it from source jars. This means the source jars have to be available and known to your project.

Let's try to trouble shoot it a little.

First, we can check if source code for the JRE classes like java.lang.String can be found by Eclipse. Just try opening the 'String' class (e.g by doing CRL-click on an occurrence of 'String' in your source code). Does it open the source code of the String class in the editor? Or do you just get an editor with some 'missing source code attachement' message?

Second. Let's look at the the details of your source attachement of the JRE jars. Navigate down in the 'JRE System Library' node in he project view. Then right click on 'java.base' and select 'Properties' from context menu. Select the 'Source Attachement' tab.

In my case I see that the 'java.base' source attachment points to a 'External Location' with path /home/kdvolder/Applications/jdk-11.0.3/lib/src.zip.

Where does it point for you? Is there a zip file there that actually contains source code for the jre?

Depending on how you installed the JVM the source may not be included. Some distributions will not ship the sources just to save space. If I had to make a guess, this is probably the case for you.

[4javier]

As I wrote in the last line of my original message, explicitly attaching sources to JRE libs make Eclipse correctly show the Javadoc.
But about this statement of yours

Eclipse (a bit surprising to most people) doesn't actually show javadoc by looking for javadocs from html files, but instead extracts it from source jars. This means the source jars have to be available and known to your project.

I'm a bit skeptical: what's the point of being able to specify Javadoc location for a JRE, if I'm forced to specify even the source anyway? Just for the internal browser?
Window→Preference→Java→Installed JREs→Edit→Javadoc Location

[martinlippert]

@4javier I am a bit puzzled about this, too (to be honest). But I would like to understand whether this is a general Eclipse issue or something that is specific for the Spring Tools 4 for Eclipse distribution. And in case this is a general Eclipse issue, we should for sure report this to Eclipse and discuss it with the team over there. What do you think? Would you like to double check this with a plain Eclipse install as a first step?

[4javier]

@martinlippert
Done. It happens with plain Eclipse 4.15 too.
I installed it from Arch Linux Community repo.
@kdvolder
Would you please try to detach src from base library and tell me if the simple attached Javadoc works for you? If the latter, I'd try to ask for support on my distro forum before contacting eclipse devs.

[kdvolder]

I'm a bit skeptical: what's the point of being able to specify Javadoc location for a JRE

Not disagreeing with you really. As I said many folks finds this surprising / illogical. Actually I found it surprising myself when I figured this out for myself a long time ago. But it has been working like that for as long as I can remember, which is many many years.

. It happens with plain Eclipse 4.15 too.

So, it may be worth raising a bug about this with Eclipse bugzilla as Martin suggested. There's definitely a case to be made that this is a bug at worst, or at the very least an awkward ui design that could be improved upon.

Would you please try to detach src from base library and tell me if the simple attached Javadoc works for you? If the latter, I'd try to ask for support on my distro forum before contacting eclipse devs.

I tried and indeed, as soon as I removed the source attachement info... then Java doc for 'String' class is no longer being shown in hover text.

I'd try to ask for support on my distro forum before contacting eclipse devs

You could do both, actually.

You could ask about including sources with the JDK from your distro because having sources is just convenient for a developer. However my guess is that they will not do this as they have more than likely considered this question carefully already and decided that most people don't want or need the sources and, for those who do, there is probably already an optional package that you can install to get the source added on.

Independent of this, it also makes sense to raise Eclipse bug ticket too. I don't think anybody will disagree with you that the way this works is illogical and confusing to users.

[kdvolder]

if I'm forced to specify even the source anyway ...

Just to clarify. I never had to 'specify' this myself. I just pointed Eclipse at the JDK folder I downloaded and unzipped. And Eclipse found the location of the sources itself.

If it doesn't work like that for you then it is probably either because of one of two possible reasons:

• the source zip file is not installed/present at all.
• the source zip is installed, but its not in the typical places where Eclipse tries to find it.

It may be good to determine which of these two cases you are in before deciding what to ask on Eclipse-bug or ArchLinux forum.

[kdvolder]

I did a quick google and found this existing Eclipse bug:

https://bugs.eclipse.org/bugs/show_bug.cgi?id=549029

Seems like the same issue (i.e. user complaining about not getting JavaDoc after removing source attachement). So instead of creating new bugzilla ticket probably better to add your voice to that one.

Anyhow I think from the info we have... I don't think this is a problem specific to STS. So I'll close this issue now. Don't let that stop you from posting more comments / questions here though, if you disagree or for whatever other reason.

[kdvolder]

@4javier

I've added a comment of my own to the Eclipse bug.

https://bugs.eclipse.org/bugs/show_bug.cgi?id=549029#c3

I suggest you do the same. Looks like the bug hasn't drawn much attention / repsonse, but the more people express they have this problem the more likely something will be done about it.

[4javier]

@kdvolder
Thanks for your efforts.
I commented the ticket.

To make things clear:
Arch Linux ships binary, docs and source for JDK in three different packages, letting the user free to choose what to download and what not. Using the source provided by repo and making Eclipse look at their installation_path/src.zip, everything works as expected. Same thing using the archive downloaded from Oracle site.
Then the "problem" is totally on Eclipse side.

I found a few old tickets (even from 2003!!!) citing this problem.
https://bugs.eclipse.org/bugs/show_bug.cgi?id=41421

I think is not a "feature" because I found online a lot of tutorial for different external libraries, that explains how to download just their docs and make Eclipse finding it to be shown in popup and Javadoc view.

I suspect it's a regression that occurs often in Eclipse releases.

[kdvolder]

I suspect it's a regression that occurs often in Eclipse releases.

I'd say that you are probably right. But I can't say so for sure. If it is regression, it is possible it was broken a loong time ago. And it is likely that it wasn't noticed by most people and didn't get attention because, developers typically do install the source jars, and in that case, everything works as expected.

So, I think its good to report this, but I wouldn't get my hopes up too much for a fix anytime soon.

Realistically, the bug probably doesn't seem important enough because it doesn't affect too many people.

For you personally, I would recommend you just install the JDK source jars. It is actually nice to be able to navigate into the source of various JRE libraries you are using. I find that tremenously helpful myself to understand what they do and how they work (in addition to just reading the JavaDoc). It is also especially helpful when debug stepping through code (which sometimes you end up in JRE classes you want to step through).

[kdvolder]

Actually, looking at the 'old ticket' you dug up, It seems this is indeed something that is supposed to work. It is hard to ever be 100% sure, but I think that seems pretty conclusive.

You might want to link that issue in to the one we commented on. It's useful information and might help convince that this something in need of fixing.

[4javier]

@kdvolder
Done.
Even if, after some days trying to get support in Eclipse forum and IRC channel, I sincerely doubt anyone will be interested about it in a short time.

[Erano01]

I am an arch linux user and I had the same problem. I have overcome this problem at the end of the day. I would like to note that if you are downloading jdk packages, you should also download javadoc and source packages. After this, the src.zip folder will be created.
sudo pacman -S jdk8-openjdk jdk11-openjdk jdk17-openjdk jdk-openjdk openjdk8-doc openjdk11-doc openjdk17-doc openjdk21-doc openjdk8-src openjdk11-src openjdk17-src openjdk21-src