Component Report

The Component Report module lets you generate comprehensive documentation for all the components in your module (either a component library or a Tapestry application).

For each component, the inheritance, description and complete set of parameters (including inherited parameters) are displayed.

The documentation is generated from a mix of JavaDoc and annotations on the classes themselves, and from external documentation you may provide.

External Documentation

The external documentation is optional, and takes the form of a file, stored in the same package as the component class, with the extension ".xdoc".

External documentation is in the Maven XDoc Format, which can be thought of as a somewhat rigid, stripped down version of XHTML.

The component report will extract the content of the <body> element and add it to the documentation it automatically generates. It will also copy any images (the src attribute of any <img> element) to the corresponding output folder.

The documentation is generated into a directory structure that mimics the package structure; thus a link to component documentation for components in the same package is just a link to another file (with a .html extension) in the same folder.

Example:

<document>
    <body>
        <section name="Related Components">
            <ul>
                <li><a href="Foo.html">Foo</a></ul>
                <li><a href="Bar.html">Bar</a></ul>
            </ul>
         </section>
         <section name="Examples">
            <p>The Baz component can be used to generate a gloop style of interface:</p>
            <p><img src="baz_ref.png"/></p>
            . . .

External documentation files (the .xdoc files and any related image files) can be either on the Java main path (i.e., src/main/java) or on the resources path (src/main/resources). At this time, you should place them under src/main/java such that the files are not packaged in your library JAR or application WAR.

Generating the Report

Just add the following to the reporting/plugins section of your POM:

<plugin>
    <groupId>org.apache.tapestry</groupId>
    <artifactId>tapestry-component-report</artifactId>
    <version>5.0.x</version>
    <configuration>
        <rootPackage>org.example.myapp</rootPackage>
    </configuration>
</plugin>

Be sure the update the <version> element with the current version of the Maven plugin, and update the <rootPackage> element with the value for your application (this will match the value you configure inside your web.xml).

Added in 5.3

Unknown macro: {div}

 

In version 5.3 the configuration of the Maven plugin changed in a backward incompatible way. The configuration expects the <rootPackages> element, which may have several <rootPackage> elements. You should change the plugin configuration as shown below or you can still use the 5.2.4 version of the plugin without to change anything.

<plugin>
    <groupId>org.apache.tapestry</groupId>
    <artifactId>tapestry-component-report</artifactId>
    <version>5.3.x</version>
    <configuration>
        <rootPackages>
           <rootPackage>org.example.myapp</rootPackage>
           <rootPackage>com.acme.lib</rootPackage>
        </rootPackages>
    </configuration>
</plugin>

Limitations

There is no ability to generate parameters for base classes from another library; the tools assume that the components are entirely self-contained within the current model.