Adding JavaDoc to help system

Sometimes it is useful to provide JavaDoc documentation to the user. While adding such documentation to an RCP application might be a special case it could make more sense to have such documentation ready for Eclipse extensions. If you combine this with custom doclets you might generate even more than just API documentation.

Instead of adding external html files we will add this documentation to the Eclipse help system.

Source code for this tutorial is available on googlecode as a single zip archive, as a Team Project Set or you can checkout the SVN projects directly.

Step 1: Create JavaDoc

First lets create a place to store our generated files in. So create a new Plug-in Project called com.example.javadoc.

Now select the menu entry Project / Generate Javadoc....

You need to define the javadoc executable, the source files to be parsed and the destination where to create html files. We will set the latter to com.example.javadoc/javadoc.

On the last wizard page you have the option to save all settings to an ant script so you can regenerate your documentation easily.

 

After finishing the wizard you are asked whether to update the javadoc location or not. Say No To All here.

When you refresh your project in the navigator you should see the generated files.

Step 2: Optimize build process

Refreshing by hand is nasty, why not let Eclipse do the job for us? Select your generate_javadoc.xml, right click and select Run As / Ant Build ... On the Refresh tab you can adjust which resources to refresh after the build process.

Step 3: Adding files to Eclipse help

There exist lots of tutorials on how to add help content to eclipse. As a starting point take a look at Contributing a little help or Lars' tutorial on Adding Help to RCP Applications.

We will create a book with a single section containing our help content. Create the book by adding a new file help/book.xml to our project:

<?xml version="1.0" encoding="UTF-8"?>
<toc label="Sample Book">
 <topic label="API Documentation">
  <link toc="help/API_documentation.xml" />
 </topic>
</toc>

Now add another file help/API_documentation.xml:

<?xml version="1.0" encoding="UTF-8"?>
<toc label="Sample API">
 <topic label="JavaDoc" href="javadoc/index.html" />
</toc>

You can open/edit these files with the Table of Contents Editor, which gives you a nicer UI to create such files, but usually the XML is simple enough to remain in the text editor.

To add these files to Eclipse help we need to use extension points. Open your MANIFEST.MF file and switch to the Extensions tab. Create a new extension for org.eclipse.help.toc and create two toc child nodes. Each of them refers to one of our xml files. To create a new book (which is displayed as a root level element in the help contents) we need to set primary to true.

The final plugin.xml should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension
         point="org.eclipse.help.toc">
      <toc
            file="help/book.xml"
            primary="true">
      </toc>
      <toc
            file="help/API_documentation.xml"
            primary="false">
      </toc>
   </extension>
</plugin>

Finally switch to the Build tab and make sure help and javadoc folders are included in the Binary Build.

Run your application and select Help / Help Contents to see our new book in action.

Optional: Open a help page programmatically

The help system allows to open dedicated pages on demand. You can open an html page by calling

PlatformUI.getWorkbench().getHelpSystem().displayHelpResource("/<plugin ID>/path/to/your/file.html");

Further improvements

Currently the creation of JavaDoc is still a manual process. But we could combine this with the Custom Builder tutorial and let the builder run javadoc. Then you could add the builder to all your projects that contribute to your javadoc files.