Tapestry 5.3 release candidate is out and the final release is approaching. That’s why I want to share with you a new cool feature which will make your life easier.

As a Tapestry user you surely know Tapestry’s component reference documentation. This documentation is generated using Tapestry’s Maven plugin. Many of Tapestry users, who are also Maven users, are using this plugin for their custom components. Unfortunately there was no solution for non-Maven users before Tapestry 5.3.

Starting with version 5.3 Tapestry provides a JavaDoc plugin which can be used to generate a component reference documentation as part of JavaDoc. An example is demonstrated in the following screenshot.

Check out this JavaDoc to see what is possible with the new JavaDoc plugin.

What is needed to integrate a component reference into the JavaDoc? You just need to place @tapestrydoc on the component’s classes, as shown in the following example.

/**
 *  Here comes your JavaDoc...
 *
 * @tapestrydoc
 */
public class MyComponent {
   ...
}

Additionally you need to use Tapestry’s taglet when generating the JavaDoc. For more details on JavaDoc Taglets see here.

Integration with Maven

Now let’s see how to tell Maven’s JavaDoc plugin to use Tapestry’s taglet.

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.8</version>
        <configuration>
          ...
          <taglet>org.apache.tapestry5.javadoc.TapestryDocTaglet</taglet>
          <tagletArtifact>
             <groupId>org.apache.tapestry</groupId>                       
             <artifactId>tapestry-javadoc</artifactId>                       
             <version>5.3-rc-3</version>                   
          </tagletArtifact>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </reporting>
  ...
</project>

That’s all. Tapestry’s JavaDoc plugin will do the rest and generate kickass JavaDocs.

Integration with Gradle

If you are interested how to generate the component reference with Gradle, please check out Tapestry’s build script.

Integration with Ant

Honestly I have no idea how to do that as I didn’t use Ant for years. I’m pretty sure it is possible. Please read the documentation for Ant’s JavaDoc plugin for more details.

Stay tuned!