Search code examples
javaeclipseeclipse-pluginjavadoc

Is there any way to automate Javadoc attachment for non-JRE bundles in Eclipse?

First, this is not about the Java SE Javadocs. That's working fine.

We have a large Java-based platform, with about 20 API bundles. For people who use our platform, we'd like tooltips and other such built-in doc support to work just as it already does for the Java APIs.

Our Javadocs are at a URL available to those who use our platform, and work properly when manually attached to a referenced bundle using the usual approach.

Eclipse doesn't seem to persist the Javadoc attachment - that is, when you attach Javadocs to a bundle, it works, but when you restart Eclipse, that attachment is lost.

With at least 20 API bundles, and a typical workspace using our platform having at least 10 or more projects, having to manually attach Javadocs to each referenced bundle for each project is not workable (could be 200 manual attachments, e.g.) each time Eclipse is restarted.

Is there any way for this to be automated? I'm not above some kind of scripting solution, even if it had to be run each time Eclipse was started, though clearly, it would be better if it just "worked", the way it does for the Java APIs. (For that matter, I'd love this to also work for various things like Apache Commons, Bouncy Castle, Android, etc.).

Thanks...

Solution

  • This problem can be solved by providing a bundle containing Javadoc with your Target Platform (no source code included). Here are the steps to achieve this:

    1. Create plug-in containing full Javadoc of your API
    2. Define extension via org.eclipse.pde.core.javadoc extension point in this plug-in like this:
    <extension point="org.eclipse.pde.core.javadoc">
    <javadoc path="javadoc"> <!-- relative path to the API javadoc directory (can also be a URL) -->
        <plugin id="com.acme.core"/>
        <plugin id="com.acme.ui"/>
        <!-- list plug-ins which have been documented in the docs -->
    </javadoc>
</extension>
    1. Export this plug-in and add it to the Target Platform

    In case your Javadoc is already available online via URL, you can just create the plug-in defining an extension and set a URL as a path of the Javadoc element:

    <javadoc path="https://acme.com/apidocs">

    Eclipse IDE will automatically resolve Javadoc location through the PDE extension for your bundles.