AntDoclet is a tool to automatically generate documentation out of your Ant Tasks' source code.
It is implemented as a Javadoc doclet, and generates reference documentation and other deliverables from the source code of your custom Ant Tasks/Types. It's been only tested with JDK 1.4.
It uses template-based generation, using
Velocity. This makes it simple to
create new deliverables or modify the ones provided. The example
templates generate HTML and LaTeX (PDF) and are located under the
templates/
directory.
The example.build.xml
file is an example of how to run the doclet from
Ant. You must change some properties to fit your needs, like the path to
your tasks source code and compiled classes. If you need AntDoclet, I assume
you are comfortable with Ant scripts ;-).
IMPORTANT: The doclet needs access to both the source code and the compiled version of the tasks/types to document. This is so because AntDoclet uses the same runtime-reflection mechanism that Ant itself uses to find valid properties and nested elements from each task/type.
AntDoclet expects some ant-specific tags to build richer documentation:
-
The javadoc comment of a class should have either the tag
@ant.task
(for Tasks) or tag@ant.type
(for Types used from ant Tasks). Both accept three "attributes":category, name, ignored
. Examples:@ant.task name="copy" category="filesystem" @ant.type name="fileset" category="filesystem" @ant.task ignore="true"
When
ignore
is true, the class will not be included in the documentation. This is useful for ignoring abstract classes or tasks/types that are not to be exposed in the docs. -
Additional tag: Filter out attributes that were manually tagged for removal. Often a class (task) extends another by already setting some of the attributes of its superclass. In that it its usually not desirable that those attributes are "manually" changed to some other value. Hence they should not be listed in the documentation (although technically they can be changed!).
@ant.attribute.ignore TO_BE_IGNORED_ATTRIBUTE_NAME
-
Additional tag: Filter out nested elements that were manually tagged for removal. Often a class (task) extends another. Hence some or all of the normally legitimate nested elements should not be listed in the documentation.
@ant.nested.ignore ELEMENT_NAME
-
Additional parameter for calling Javadoc: Task names are already defined in the tasks' lib file. This paramter triggers the automatic scanning and hence makes it unnecessary to provide the name using the @ant.{task|type} tag
-taskslibfile FILE_NAME
-
Additional parameter for calling Javadoc: Java package gets mapped to a task category
-taskscategoryfile FILE_NAME
For example:
<?xml version="1.0"?>
<antlib>
<category name="Comp1" package="com.acme.framework.comp1" />
<category name="App1" package="com.acme.app1" />
</antlib>
You can store the category tags in the taskslibfile.
-
The tasks/types properties documentation is extracted from the properties setter/getter methods' comments (the setter comment has precedence). Two additional tags are accepted here:
@ant.required @ant.not-required
used to indicate that the property is (or not) required.
Additional comment can be added to the tag. Example:
/** * Overwrite any existing destination file(s). * * If true force overwriting of destination file(s) * even if the destination file(s) are younger than * the corresponding source file. * * @ant.not-required Default is false. */ public void setOverwrite(boolean overwrite) { this.forceOverwrite = overwrite; }
The javadoc comments must be valid XHTML, otherwise, the templates' output may be broken. Some suggestions:
- Make sure all HTML tags are "balanced" (properly open and close each tag).
- Separate paragraphs should be written between
<p> </p>
. - Use
<code> </code>
for variable and file names. - For displaying source code in a nice box (like code examples) use
<pre> </pre>
. - Remember to escape all necessary characters to make it valid HTML (
<
instead of<
, etc.)
Thanks,
Fernando Dobladez (http://code54.com)