Do we still need generated platform API javadocs?

[iloveeclipse]

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.

[mickaelistria]

+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.

[HannesWell]

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.

[iloveeclipse]

OK, I will ask on platform-dev and cross project lists too.

[iloveeclipse]

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.

[mickaelistria]

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.

[vogella]

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)

[jonahgraham]

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

[laeubi]

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.

[iloveeclipse]

See "API Reference" / "Extension Point Reference" topics under each of "XYZ Plugin Developer Guide" chapters.
Here is what happens if they are broken: before/after:

[mickaelistria]

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

[iloveeclipse]

If anyone looks at that, please update https://github.com/eclipse-platform/.github/wiki/Javadoc-validation#expected-flow
The old wiki will gone soon anyway.

[laeubi]

if you're willing to try changes to the javadoc generation process

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).

[laeubi]

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.

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.
This also includes external sources like for junit and alike where it defines an URL where to find javadoc.

For the first, I have created a new issue at Tycho, that should allow to better deploy (and probably install) individual javadocs:

• Support deploy of javadoc to an update site eclipse-tycho/tycho#2330

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:

https://github.com/eclipse-platform/eclipse.platform.common/blob/d44d20bc3e1e802f8a16555d09fe9d9153b03597/bundles/org.eclipse.jdt.doc.isv/plugin.xml#L51-L92

JDT defines some URLs for the javadoc of Junit, something that might better be directly declared at:
https://github.com/eclipse-jdt/eclipse.jdt.ui/blob/master/org.eclipse.jdt.junit/plugin.xml

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.
But one can also think to maybe even better manage such mappings then at PDE directly, e.g. pde core (as PDE requires jdt anyways).

[mickaelistria]

so one could install the jar + the isv stuff and (even if no source are there) gets javadoc for the bundles

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.

[laeubi]

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.

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 plugin.xml of the common bundles so we can reduce the burden of migration as much as possible.

[HannesWell]

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?
E.g. https://github.com/eclipse-platform/eclipse.platform.common/tree/master/bundles/org.eclipse.pde.doc.user to the pde repo, the platform bundles to the correponding platform repos etc. and close https://github.com/eclipse-platform/eclipse.platform.common?

[stephan-herrmann]

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?

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 org.eclipse.jdt.annotation. A link to javadoc is the perfect match for this. Similar situations arise when writing a blog post on such topic.

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.

[akurtakov]

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 .

[laeubi]

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 .

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.

[akurtakov]

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.