Apache Tapestry > Documentation > User Guide > Component Report

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

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.