You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by hl...@apache.org on 2008/02/06 18:20:44 UTC
svn commit: r619077 -
/tapestry/tapestry5/trunk/tapestry-component-report/src/site/apt/index.apt
Author: hlship
Date: Wed Feb 6 09:20:41 2008
New Revision: 619077
URL: http://svn.apache.org/viewvc?rev=619077&view=rev
Log:
TAPESTRY-2076: Component report should break out as one class per page and include examples
Modified:
tapestry/tapestry5/trunk/tapestry-component-report/src/site/apt/index.apt
Modified: tapestry/tapestry5/trunk/tapestry-component-report/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-component-report/src/site/apt/index.apt?rev=619077&r1=619076&r2=619077&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-component-report/src/site/apt/index.apt (original)
+++ tapestry/tapestry5/trunk/tapestry-component-report/src/site/apt/index.apt Wed Feb 6 09:20:41 2008
@@ -7,8 +7,55 @@
This report generates a comprehensive listing of 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.
-
-* Usage
+
+ The documentation is generated from a mix of JavaDoc and annotations on the classes themselves, and from
+ external documentation you may provide.
+
+
+* Providing 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 {{{http://maven.apache.org/doxia/references/xdoc-format.html}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 documention 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 links
+ 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:
@@ -16,7 +63,7 @@
<plugin>
<groupId>org.apache.tapestry</groupId>
<artifactId>tapestry-component-report</artifactId>
- <version>5.0.2-SNAPSHOT</version>
+ <version>5.0.x</version>
<configuration>
<rootPackage>org.example.myapp</rootPackage>
</configuration>
@@ -26,11 +73,9 @@
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
- {{{http://tapestry.apache.org/tapestry5/tapestry-core/conf.html}web.xml}}).
+ {{{../tapestry-core/conf.html}web.xml}}).
* Limitations
-
- Doesn't recognize Mixins unless they have parameters.
Doesn't have any way to generate parameters for base classes from another library; the tools assume that the components
are entirely self-contained within the current model.