[platform-dev] Linkable SWT javadoc

[Ned Twigg <ned.twigg@xxxxxxxxxxxx>]

STANDARD MAVEN APPROACH

The maven convention is to have a -sources.jar and -javadoc.jar.  There are other tools and services, like javadoc.io, which build on these conventions, and help independent projects to hook together.  For SWT, the -javadoc.jar is just a README that says "Corresponding javadoc can be found in artifact org.eclipse.platform:org.eclipse.platform.doc.isv"

And if you go to that artifact on mavencentral: https://repo1.maven.org/maven2/org/eclipse/platform/org.eclipse.platform.doc.isv/4.14.0/

And download its -javadoc, you get another README that says "Corresponding javadoc can be found in artifact org.eclipse.platform:org.eclipse.platform.doc.isv".  It seems that the "code" artifact is the real one, so you can download that manually.  And when you extract it, you can find the normal javadoc convention (except without package-list) in the "reference/api" subfolder.

Eclipse is *extremely* well documented, one of the best documented projects around, but because it doesn't follow ecosystem conventions, it's hard for people who aren't "in-the-know" to figure out how to get those docs.

MY ATTEMPTED WORKAROUNDS

I am a little bit in the know, so I tried to find and publish a workaround.  For example, I know that the SWT javadoc is hosted here: https://help.eclipse.org/2019-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/package-summary.html

There isn't a package-list that I could find, so you can't do the normal thing where you tell the javadoc tool "https://docs.oracle.com/javase/8/docs/api/" and it adds the "package-list" automatically to find out which packages it should link to that URL.

The workaround is to make your own local package-list file, and then you can use "linksOffline" to tell the javadoc tool "use this local file to list the packages, and link them to this remote URL".  So I made my own package-list file: https://github.com/diffplug/durian-swt/blob/master/gradle/javadoc-eclipse/package-list

And pointed javadoc to it and the help.eclipse.org URL: https://github.com/diffplug/durian-swt/blob/e2200284e35687c58f0cccbd388d227b1107184f/build.gradle#L34

The result is javadoc where there are links for the SWT classes, but they refuse to load inside an iframe (help.eclipse.org refused to connect).  If you open these links in another tab, they will open fine, but it seems like help.eclipse.org is somehow configured to disallow external projects from linking to it.  And since there's nowhere else that the javadoc is hosted (that I can find), that's where I get stuck.

THE CURRENT STATE

This is an example of a javadoc that uses the workaround above, and it links back to two big projects, RxJava and SWT: https://javadoc.io/static/com.diffplug.durian/durian-swt/3.3.1/com/diffplug/common/swt/SwtRx.html 

If you click a link to "Observable", you get RxJava's very good javadoc.  And if you click "Widget" or "Control", you also get Eclipse's very good javadoc.  So far so good!  The problem is that the normal javadoc view is the iframe with the classes on the left: https://javadoc.io/doc/com.diffplug.durian/durian-swt/latest/index.html

And from this view, if you click any SWT links, your browser just tells you (help.eclipse.org refused to connect).

WAYS IT COULD BE BETTER

When I compress the SWT javadoc html, I get a 3.2MB zip file.  But the only way to get it is to download a 40MB zip file and exploring a non-standard directory layout, and even that file can only be found with a bit of detective work.  The result is that unless you are using 100% built-within-eclipse tooling, it doesn't hook up.

And even with a workaround, I still can't get it to work 100% smoothly.

Anyway, love eclipse, love SWT, just leaving a user story from someone unaffiliated with the Eclipse Foundation but is trying to build things that connect with it.

Ned Twigg

Lead Software Architect, DiffPlug LLC

540-336-8043 (cell)
888-513-6870 (fax)
340 S Lemon Ave #3433, Walnut, CA 91789

ᐧ