Tycho 13: Generating API documentation

If you want to add API documentation to your feature you want to make sure that documentation and implementation are consistent. Running javadoc manually is not ideal, better integrate documentation generation in your tycho build.

Tycho Tutorials

For a list of all tycho related tutorials see Tycho Tutorials Overview

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.

Step 1: Create a help plug-in

We need a hosting plug-in for our API documentation. So create a new Plug-in Project named com.codeandme.tycho.help and mavenize it with Packaging set to eclipse-plugin. Add it to your master pom as usual.

Eclipse help is provided by adding extension points for org.eclipse.help.toc elements and according xml files. I will not go into details here as Lars did an excellent job with his tutorial on eclipse help.

For our project we provide 2 'classic' toc entries along with xml files: main.xml and reference.xml.

The third entry in plugin.xml (referring to help/api_docs.xml) does not have a corresponding xml file as we will create this one on the fly with maven.

We intend to generate documentation to a folder help/api-docs/javadoc. As tycho will not create this folder automatically, we need to add it manually.

Step 2: Configuring tycho

Documentation creation is a step we want to do for the help plug-in only. Therefore the following changes will go to com.codeandme.tycho.help/pom.xml and not to our master pom.

 <properties>
  <platform.api>org.eclipse.platform.doc.isv/reference/api</platform.api>
 </properties>

 <build>
  <plugins>
   <plugin>
    <groupId>org.eclipse.tycho.extras</groupId>
    <artifactId>tycho-document-bundle-plugin</artifactId>
    <version>${tycho.extras.version}</version>
    <executions>
     <execution>
      <id>eclipse-javadoc</id>
      <phase>generate-resources</phase>
      <goals>
       <goal>javadoc</goal>
      </goals>
      <configuration>
       <outputDirectory>${project.basedir}/help/api-docs/javadoc</outputDirectory>
       <tocFile>${project.basedir}/help/api_docs.xml</tocFile>
       <tocOptions>
        <mainLabel>Tycho Tutorial API</mainLabel>
       </tocOptions>
       <javadocOptions>
        <!-- enable in case you need a proxy for web access 
        <jvmOptions>
         <jvmOption>-Dhttp.proxySet=true</jvmOption>
         <jvmOption>-Dhttp.proxyHost=proxy.example.com</jvmOption>
         <jvmOption>-Dhttp.proxyPort=81</jvmOption>
         <jvmOption>-DhttpnonProxyHosts=*.example.com</jvmOption>
        </jvmOptions>
         -->
        <additionalArguments>
         <additionalArgument>${javadoc-args}</additionalArgument>
         <additionalArgument>
          -link
          http://docs.oracle.com/javase/8/docs/api/
         </additionalArgument>
         <additionalArgument>
          -linkoffline
          ../../${platform.api}
          http://help.eclipse.org/mars/topic/org.eclipse.platform.doc.isv/reference/api/
         </additionalArgument>
         <additionalArgument>-public</additionalArgument>
        </additionalArguments>
       </javadocOptions>
      </configuration>
     </execution>
    </executions>
   </plugin>
  </plugins>
 </build>

The property tycho.extras.version was added in our previous tutorial. Please add it to the master pom, if you did not do this already.

Lets look at some of the pom options:

Line 20 defines the TOC xml file to be created. Its display name is defined in line 22. TOC generation might be disabled by setting <skipTocGen>false</skipTocGen>
Lines 35-38 will add links to external documentation for standard java classes.
Lines 39-43 will add links to the eclipse API documentation typically shipped with every release.

Step 3: Define plug-ins for documentation creation

Typically you do not want to create documentation for all plug-ins. Test plug-ins for example should not show up there. Therefore we need to maintain a list of all plug-ins that should be considered by tycho.

This list is stored in com.codeandme.tycho.help/build.properties. Add them as extra classpath entries:

jars.extra.classpath = platform:/plugin/com.codeandme.tycho.plugin

To provide multiple plug-ins, add a comma-separated list (like for the bin.includes entry).

Tycho will create documentation for exported packages only. With the current project configuration com.codeandme.tycho.plugin does not export anything. You have to export a package there or tycho will fail to build.

Finally make sure to add the help folder to your binary build in build.properties.

Congratulations, you API documentation is now up to date for every build.