ANT doclet

From unkrig.de
(Difference between revisions)
Jump to: navigation, search
(Related attributes)
m (Grouping of subelements)
Line 41: Line 41:
 
Sometimes you want to document multiple attributes ''together'', i.e. have only ''one'' description. To get that, write a doc comment with a description for the ''first'' setter, and for the other setters a doc comment with a ''sole'' @see tag that refers to the first setter. Here is an [http://antology.unkrig.de/antdoc/tasks/swingLookAndFeel.html#attributes_summary example].
 
Sometimes you want to document multiple attributes ''together'', i.e. have only ''one'' description. To get that, write a doc comment with a description for the ''first'' setter, and for the other setters a doc comment with a ''sole'' @see tag that refers to the first setter. Here is an [http://antology.unkrig.de/antdoc/tasks/swingLookAndFeel.html#attributes_summary example].
  
=== Grouping of subelements ===
+
=== Grouping of attributes and subelements ===
  
Subelement adder methods ("<code>add*()</code>", "<code>addConfigured*()</code>" and "<code>create*()</code>") can have a "<code>@ant.group</code> ''group-name''" block tag in their DOC comment. If at least one subelement adder method has such a block tag, then the subelements are grouped by ''group-name'', and each group gets a respective heading, and the subelements without a <code>@ant.group</code> go into a group "Other".
+
Attribute setter methods ("<code>set*()</code>") and subelement adder methods ("<code>add*()</code>", "<code>addConfigured*()</code>" and "<code>create*()</code>") can have a "<code>@ant.group</code> ''group-name''" block tag in their DOC comment. If at least one attribute setter method (resp. subelement adder method) has such a block tag, then the attributes (resp. subelements) are grouped by ''group-name'', and each group gets a respective heading, and the subelements without a <code>@ant.group</code> go into a group "Other".
 
+
For an example, see [http://zz.unkrig.de/antdoc/tasks/zzfind.html the documentation of the <zzfind> ANT task], and [https://svn.code.sf.net/p/loggifier/code/trunk/de.unkrig.zz.find/src/de/unkrig/zz/find/AbstractElementWithExpressions.java the source code].
+
  
 
=== Attribute value documentation ===
 
=== Attribute value documentation ===

Revision as of 11:24, 10 February 2017

Generates (JAVADOC-like) HTML documentation for APACHE ANT antlibs.

The motivation for writing this doclet is to ease the maintenance of the documentation for the Ant-contrib.unkrig.de antlib:

Antdoc-ant-contrib.png

Contents

Usage

The doclet implements the following command line options:

-d directory
-windowtitle window-title
-doctitle document-title
-header header
-footer footer
-top top
-bottom bottom
-notimestamp true|false
-link url-or-file
-linkoffline url-or-file package-list-url-or-file
Same as for the standard JAVADOC doclet
-antlib-file file
The antlib file of the antlib to document; defaults to "antlib.xml".
-theme JAVA7|JAVA8
The style of the generated pages.

Features

Basics

The doclet parses the "ANTLIB file" of your ANTLIB to identify all the tasks, types, chainable readers etc. that the ANTLIB implements. Then it finds the attribut setter and subelement adder methods, just like ANT would do. Eventually it generates one HTML page for each task, type, chainable reader etc., plus various overview, summary, index and frameset pages; very similar to what the standard JAVADOC servlet does for a set of Java classes.

References to attribute setter and subelement adder methods are not rendered as "setFoo(String)" and "addPerson(Person)", but like "foo=..." and "<person>".

Links to the various standard ANT types are recognized and rendered appropriately.

Related attributes

Sometimes you want to document multiple attributes together, i.e. have only one description. To get that, write a doc comment with a description for the first setter, and for the other setters a doc comment with a sole @see tag that refers to the first setter. Here is an example.

Grouping of attributes and subelements

Attribute setter methods ("set*()") and subelement adder methods ("add*()", "addConfigured*()" and "create*()") can have a "@ant.group group-name" block tag in their DOC comment. If at least one attribute setter method (resp. subelement adder method) has such a block tag, then the attributes (resp. subelements) are grouped by group-name, and each group gets a respective heading, and the subelements without a @ant.group go into a group "Other".

Attribute value documentation

The ANT doclet visualizes the meaning, the possible values and the default values for each attribute. The meaning is derived from the method parameter type and name (or the @ant.valueExplanation block tag); the possible values (for enums) from the enum constants, and the (optional) default value from the method parameter type and the @ant.defaultValue block tag.

The @ant.mandatory block tag appends " (mandatory)" to the attribute description title.

Custom type groups

The ANT doclet analyzes the types and, based on the interfaces they implement, assigns them to "type groups", which will later appear in the left-hand-side frame. The well-known type groups are: "Tasks", "Resource collections", "Chainable readers", "Conditions and "Other types". It is also possible to assign types to your own custom type groups, by adding the following block tags to the type:

/**
 * This type lives in a custom "type group". For this example, we re-use the values for the "Tasks" type group -- please use your own instead.
 *
 * @ant.typeGroupSubdir  tasks
 * @ant.typeGroupName    Task
 * @ant.typeGroupHeading Tasks
 * @ant.typeTitleMf      Task "&lt;{0}&gt;"
 * @ant.typeHeadingMf    <code>&lt;{0}&gt;</code>
 */

Ordering of subelements

If an ANT type (e.g. a task) or a subelement has this block tag

/**
 * @ant.subelementOrder inheritedFirst
 */

, then the subelements inherited from superclasses and interfaces are rendered before the subelements of the actual class. The default behavior is the other way round.

Resources

The doclet JAR file is here.

Find the source code for the doclet here.

Change Log

Version 1.0.5, 2016-11-25
  • ANTLIB includes are now looked up through the javadoc sourcepath AND the javadoc classpath.
  • Modified the text of the copyright notice slightly: Replaced "author" with "copyright holders and contributors".
Version 1.0.4, 2016-11-15
  • The "-doctitle" command line option had no effect.
Version 1.0.3, 2016-11-07
  • Allow for multiple "-antlib-file" options.
  • Also process NESTED antlib files.

License

The ANT doclet is available under the terms of the "new BSD license":

Copyright (c) 2015, Arno Unkrig All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of no-template nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox