Do we still need generated platform API javadocs? #108
Replies: 9 comments 11 replies
-
|
+1, that's a very good idea. HTML Javadoc is not the best way to face such documentation; Platform ships source on GitHub and also as bundles that can be discovered by good PDE or Maven tools, so it's easy to get a better view of the Javadoc thanks to the source and whichever IDE (with better navigation and so on). I don't think HTML pages of Javadoc will be missed much; and not publishing them can have the good effect that people who need doc then get closer to the source, and may be more likely to contribute later. |
Beta Was this translation helpful? Give feedback.
-
|
While I agree that in the IDE the generated javadoc artifacts are not of great value, I have to say that from time to time it was handy for me to have the javadoc as html sides available in the internet, for example to look something up on my smartphone when a computer is not available. But of course this is not a very important use case. |
Beta Was this translation helpful? Give feedback.
-
|
OK, I will ask on platform-dev and cross project lists too. |
Beta Was this translation helpful? Give feedback.
-
|
Hold on, I see that the API reference is cross-referenced from other documentation we ship, like here: https://help.eclipse.org/2023-03/topic/org.eclipse.platform.doc.isv/guide/resAdv_efs_api.htm?cp=2_0_11_6_0 ... If we remove API javadocs, all these references will show into nirvana. |
Beta Was this translation helpful? Give feedback.
-
|
Previous versions would still be there; but references to https://help.eclipse.org/latest/ may be broken. I personally don't care about that problem; it may not be a showstopper. I'm curious about how other committers feel about it; there might be some possible consensus that we can ignore this problem. |
Beta Was this translation helpful? Give feedback.
-
|
I think we also use it these days to mark API for deletion. But I agree that it hardly of any use, so +1 for removal the generation (and the link in the documentation to it) |
Beta Was this translation helpful? Give feedback.
-
|
I am ok with removing the generated javadocs, but only if API removal returns to be documented fully. Back in Sept when that policy was changed the recommendation was to look at previous version javadoc to find out what may be removed - https://www.eclipse.org/lists/eclipse-dev/msg12063.html |
Beta Was this translation helpful? Give feedback.
-
|
Can someone point to where the generated javadoc is integrated into this Help pages? I'll try to take a look here if we probably can adjust the build setup here. My idea would be that javadoc is generated as part of the usual bundle build and then just aggregated but first need to find out how it is actually become part of that referenced site. |
Beta Was this translation helpful? Give feedback.
-
|
See "API Reference" / "Extension Point Reference" topics under each of "XYZ Plugin Developer Guide" chapters.
|
Beta Was this translation helpful? Give feedback.
-
|
There is this documentation page that may provide interesting entry-points if you're willing to try changes to the javadoc generation process: https://wiki.eclipse.org/How_to_add_things_to_the_Eclipse_doc |
Beta Was this translation helpful? Give feedback.
-
|
If anyone looks at that, please update https://github.com/eclipse-platform/.github/wiki/Javadoc-validation#expected-flow |
Beta Was this translation helpful? Give feedback.
-
My plan would be to replace at least the ant calls with a maven plugin (like already done with api-tools now), this will then allow to easier debug and understand issues and we are much more flexible (e.g. getting all dependencies), a quick look at the current process shows that we somehow call maven dependency plugin, but this can give incomplete results (and therefor maybe we have all these extra added dependencies). |
Beta Was this translation helpful? Give feedback.
-
Looking deeper in what is produced here, it seems that the data is not only for the website, but also declares where PDE can find javadocs for a bundle, so one could install the jar + the isv stuff and (even if no source are there) gets javadoc for the bundles. For the first, I have created a new issue at Tycho, that should allow to better deploy (and probably install) individual javadocs: That way it should be possible to reference these in a feature instead that pulls in the stuff (e.g. into an EPP). for the second (the URL only items) one should actually be able to migrate this to one of the plugins, e.g. here: JDT defines some URLs for the javadoc of Junit, something that might better be directly declared at: but the problem is that this is a PDE extension point and at least Eclipse then always wants to require the bundle (even though I don't know if it is a requirement for an extension point to work), so it was "externalized" into this plugin. |
Beta Was this translation helpful? Give feedback.
-
That would have to be discussed, but my first impression is that from the SDK perspective and for the Eclipse Project in general, we don't really care about that case. We recommend developers to have sources in their target platforms anyway. |
Beta Was this translation helpful? Give feedback.
-
Sure I just describe whats the current state is and what is possible with the "isv", if thats no longer required/wanted, the first step should be to remove these items from the |
Beta Was this translation helpful? Give feedback.
-
|
In case the java-doc generation can be retained, simplified and migrated to maven, wouldn't it then make sense to move the doc bundles into the git repos of the projects they are documenting? |
Beta Was this translation helpful? Give feedback.
-
Not sure if this original question is still being discussed, but let me add that I'm currently trying to fix a N&N entry in the web, that needs to link to the specification of an annotation from So, yes, having javadoc linkable in the web is desirable - I just hope it's affordable, too. As for maintaining the doc bundles: yes, moving those closer to the individual teams sounds like a good idea, so we get back the write access we used to have before the move to github. |
Beta Was this translation helpful? Give feedback.
-
|
It's already done for PDE - https://github.com/eclipse-pde/eclipse.pde/tree/master/org.eclipse.pde.doc.user . So it's JDT bundles that are pending move and Equinox never had its own doc bundles . |
Beta Was this translation helpful? Give feedback.
-
The problem is that JDT is split across multiple repositories and docs spawn across all of them (and some platform stuff), so if one want this, it would be required to either merge all jdt repositories, or have a "jdt aggregator" (for example https://github.com/eclipse-jdt/eclipse.jdt) that includes them as submodules like the platform.aggregator does) at laest if one not just only wants to move the docs but also be able to build them independent from aggregator build. |
Beta Was this translation helpful? Give feedback.
-
|
True. And JDT aggregator will require recursive tagging (if current procedures are followed) from o.e.releng.aggregator -> o.e.jdt -> o.e.jdt.[core|debug|ui]. I haven't thought about that and it makes it look far more effort than I can spent for now. |
Beta Was this translation helpful? Give feedback.
-
Similar documentation is generated on every SDK build: https://help.eclipse.org/2023-03/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Findex.html
But is anyone on earth still using this for anything? In my ~20 years hacking around platform I've not a single time used it.
The developers will most likely use SDK to develop bundles for platform, and the Javadoc is there given because it can be read directly from sources.
So should we simply stop producing it with SDK & save our time patching ancient ant files?
I'm asking because we have so much pain reverse engineering build fails in this very old code (see eclipse-jdt/eclipse.jdt.ui#484), that it doesn't justify the return of investment anymore.
Beta Was this translation helpful? Give feedback.
All reactions