ANT doclet: Difference between revisions

From unkrig.de
Jump to navigation Jump to search
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
Generates (JAVADOC-like) HTML documentation for [http://ant.apache.org APACHE ANT] antlibs.
Generates (JAVADOC-like) HTML documentation for [http://ant.apache.org APACHE ANT] antlibs.


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


[[File:antdoc-ant-contrib.png|border|500px]]
[[File:antdoc-ant-contrib.png|border|500px]]
Line 7: Line 7:
== Usage ==
== Usage ==


The doclet implements the following command line options:
<html>


;<code>-d</code> ''directory''
<h3>Doclet command line options:</h3>
:The directory where the output files are created; defaults to ".".


;<code>-windowtitle</code> ''window-title''
<dl>
;<code>-doctitle</code> ''document-title''
  <dt><code>-d</code> <var>directory</var></dt>
;<code>-header</code> ''header''
  <dd>Where to create documentation in HTML format (optional).
;<code>-footer</code> ''footer''
<p>
;<code>-top</code> ''top''
  The effective file name is:
;<code>-bottom</code> ''bottom''
</p>
;<code>-notimestamp true|<u>false</u></code>
<p>
;<code>-link</code> ''url-or-file''
  <code>&lt;dest-dir&gt;/&lt;ant-type-group&gt;/&lt;ant-type&gt;.html</code>
;<code>-linkoffline</code> ''url-or-file'' ''package-list-irk-or-file''
</p>
:Same as for the standard JAVADOC doclet
<p>
  The default destination directory is "<code>.</code>".
</p></dd>
  <dt><code>-splitindex</code></dt>
  <dd>Splits the index file into multiple files, alphabetically, one file per letter, plus a file for any index
entries that start with non-alphabetical characters.</dd>
  <dt><code>-docencoding</code> <var>charset</var></dt>
  <dd>The charset to use when writing the HTML files. The default is the JVM default charset, "${file.encoding}".</dd>
  <dt><code>-charset</code> <var>name</var></dt>
  <dd>The HTML character set for this document.</dd>
  <dt><code>-doctitle</code> <var>html-text</var></dt>
  <dd>The title to place near the top of the overview summary file. The text specified in the title tag is placed as
a centered, level-one heading directly beneath the top navigation bar. The title tag can contain HTML tags and
white space.</dd>
  <dt><code>-header</code> <var>text</var></dt>
  <dd>The header text to be placed at the top of each output file. The header is placed to the right of the upper
navigation bar. The header can contain HTML tags and white space.</dd>
  <dt><code>-footer</code> <var>text</var></dt>
  <dd>The footer text to be placed at the bottom of each output file. The footer value is placed to the right of the
lower navigation bar. The footer value can contain HTML tags and white space.</dd>
  <dt><code>-top</code> <var>text</var></dt>
  <dd>The text to be placed at the top of each output file.</dd>
  <dt><code>-bottom</code> <var>text</var></dt>
  <dd>The text to be placed at the bottom of each output file. The text is placed at the bottom of the page,
underneath the lower navigation bar. The text can contain HTML tags and white space.</dd>
  <dt><code>-quiet</code></dt>
  <dd>Suppress normal output.</dd>
  <dt><code>-notimestamp</code></dt>
  <dd>Suppresses the time stamp, which is hidden in an HTML comment in the generated HTML near the top of each page.
This is useful when you want to run the javadoc command on two source bases and get the differences between diff
them, because it prevents time stamps from causing a diff (which would otherwise be a diff on every page).
The time stamp includes the javadoc command release number.</dd>
  <dt><code>-antlib-file</code> <var>file</var></dt>
  <dd>The ANTLIB file to parse, see <a href="https://ant.apache.org/manual/Types/antlib.html">the documentation of
the ANTLIB concept</a>.</dd>
  <dt><code>-antlib-resource</code> <var>name</var></dt>
  <dd>The name of an ANTLIB resource to parse, see <a href="https://ant.apache.org/manual/Types/antlib.html">the
documentation of the ANTLIB concept</a>.</dd>
  <dt><code>-link</code> <var>external-documentation-url</var></dt>
  <dd>See <a href="http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDEDJFI">the JAVADOC
tool documentation for the "-link" command line option</a>.</dd>
  <dt><code>-linkoffline</code> <var>external-documentation-url</var> <var>package-list-location</var></dt>
  <dd>See <a href="http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDFIIJH">the JAVADOC
tool documentation for the "-linkofflin" command line option</a>.</dd>
  <dt><code>-tag</code> <var>spec</var></dt>
  <dd>For compatibility with the standard JAVADOC doclet; ignored.</dd>
  <dt><code>-theme</code> JAVA7|JAVA8</dt>
  <dd>Which style sheets and resources to use.</dd>
  <dt><code>-sourcepath</code> <var>source-path</var></dt>
  <dd>Takes also effect for loading ANTLIB resources.</dd>
  <dt><code>-classpath</code> <var>class-path</var></dt>
  <dd>Takes also effect for loading ANTLIB resources.</dd>
  <dt><code>-windowtitle</code> <var>text</var></dt>
  <dd>See <a href="http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBIEEI">the JAVADOC
tool documentation for the "-windowtitle" command line option</a>.</dd>


;<code>-antlib-file</code> ''file''
</dl>
:The antlib file of the antlib to document; defaults to "antlib.xml".


;<code>-theme JAVA7|<u>JAVA8</u></code>
<h3>Supported tags:</h3>
:The style of the generated pages.
 
<p>
  The following block tags may appear in the DOC comment of a class declaration that maps to an ANT type:
</p>
<dl>
  <dt><code>{&#64;ant.typeGroupName <var>type-group-name</var>}</code></dt>
  <dd>
    The name of the "type group" that the type belongs to, e.g. "<code>Task</code>".
  </dd>
  <dt><code>{&#64;ant.typeGroupSubdir <var>dir-name</var>}</code></dt>
  <dd>
    The name of the subdirectory that contains the documentation of all ANT types of the type group; e.g.
    "<code>tasks</code>".
  </dd>
  <dt><code>{&#64;ant.typeGroupHeading <var>text</var>}</code></dt>
  <dd>
    The heading to display above the list of types; e.g. "<code>Tasks</code>".
  </dd>
  <dt><code>{&#64;ant.typeTitleMf <var>message-format</var>}</code></dt>
  <dd>
    The message format to use to render the heading on each type details page; e.g. <code>"Task
    &amp;quot;&amp;lt;{0}&amp;gt;&amp;quot;"</code>
  </dd>
  <dt><code>{&#64;ant.typeHeadingMf <var>message-format</var>}</code></dt>
  <dd>
    The message format to use to render the title (i.e. the tooltip) of the heading on each type details page;
    e.g. <code>"Task &amp;amp;quot;&amp;lt;code&gt;&amp;lt;{0}&amp;gt;&amp;lt;/code&gt;&amp;amp;quot;"</code>
  </dd>
  <dt><code>{&#64;ant.group <var>group-name</var>}</code></dt>
  <dd>
    Attributes (or subelements) with equal <var>group-name</var> are grouped, and the <var>group-name</var> is rendered as a heading above the group.
  </dd>
  <dt><code>{&#64;ant.subelementOrder inheritedFirst}</code></dt>
  <dd>
    Enforces that the subelements <em>inherited</em> from superclasses appear <em>before</em> the non-inherited.
    The default is that the subelements in their "natural" order.
  </dd>
</dl>
</html>


== Features ==
== Features ==


=== Grouping of subelements ===
=== Basics ===
 
The doclet parses the "[https://github.com/aunkrig/antology/blob/master/antology/src/main/resources/de/unkrig/antology/ant.xml 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 "<Code>setFoo(String)</code>" and "<code>addPerson(Person)</code>", but like "<code>foo=...</code>" and "<code><person></code>".
 
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 [http://antology.unkrig.de/antdoc/tasks/swingLookAndFeel.html#attributes_summary example].
 
=== Grouping of attributes and subelements ===
 
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".
 
=== 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 <code>@ant.valueExplanation</code> block tag); the possible values (for enums) from the enum constants, and the (optional) default value from the method parameter type and the <code>@ant.defaultValue</code> block tag.


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".
The <code>@ant.mandatory</code> block tag appends " (mandatory)" to the attribute description title.


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].
=== 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 "&amp;lt;{0}&amp;gt;"
  * @ant.typeHeadingMf    &lt;code>&amp;lt;{0}&amp;gt;&lt;/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 ==
== Resources ==


The doclet JAR file is [http://doclet.unkrig.de/ant/download/ here].
The doclet JAR file is [https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=de.unkrig&a=doclet-ant&v=LATEST&c=jar-with-dependencies here].
 
Find the source code for the doclet [https://github.com/aunkrig/doclet-ant 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.


The change log is [http://doclet.unkrig.de/ant/CHANGELOG.txt here].
* 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.


Find the source code for the doclet [https://svn.code.sf.net/p/loggifier/code/trunk/de.unkrig.doclet.ant here].
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.

Latest revision as of 12:35, 19 January 2022

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 Antology antlib:

Antdoc-ant-contrib.png

Usage[edit]

Doclet command line options:

-d directory
Where to create documentation in HTML format (optional).

The effective file name is:

<dest-dir>/<ant-type-group>/<ant-type>.html

The default destination directory is ".".

-splitindex
Splits the index file into multiple files, alphabetically, one file per letter, plus a file for any index entries that start with non-alphabetical characters.
-docencoding charset
The charset to use when writing the HTML files. The default is the JVM default charset, "${file.encoding}".
-charset name
The HTML character set for this document.
-doctitle html-text
The title to place near the top of the overview summary file. The text specified in the title tag is placed as a centered, level-one heading directly beneath the top navigation bar. The title tag can contain HTML tags and white space.
-header text
The header text to be placed at the top of each output file. The header is placed to the right of the upper navigation bar. The header can contain HTML tags and white space.
-footer text
The footer text to be placed at the bottom of each output file. The footer value is placed to the right of the lower navigation bar. The footer value can contain HTML tags and white space.
-top text
The text to be placed at the top of each output file.
-bottom text
The text to be placed at the bottom of each output file. The text is placed at the bottom of the page, underneath the lower navigation bar. The text can contain HTML tags and white space.
-quiet
Suppress normal output.
-notimestamp
Suppresses the time stamp, which is hidden in an HTML comment in the generated HTML near the top of each page. This is useful when you want to run the javadoc command on two source bases and get the differences between diff them, because it prevents time stamps from causing a diff (which would otherwise be a diff on every page). The time stamp includes the javadoc command release number.
-antlib-file file
The ANTLIB file to parse, see the documentation of the ANTLIB concept.
-antlib-resource name
The name of an ANTLIB resource to parse, see the documentation of the ANTLIB concept.
-link external-documentation-url
See the JAVADOC tool documentation for the "-link" command line option.
-linkoffline external-documentation-url package-list-location
See the JAVADOC tool documentation for the "-linkofflin" command line option.
-tag spec
For compatibility with the standard JAVADOC doclet; ignored.
-theme JAVA7|JAVA8
Which style sheets and resources to use.
-sourcepath source-path
Takes also effect for loading ANTLIB resources.
-classpath class-path
Takes also effect for loading ANTLIB resources.
-windowtitle text
See the JAVADOC tool documentation for the "-windowtitle" command line option.

Supported tags:

The following block tags may appear in the DOC comment of a class declaration that maps to an ANT type:

{@ant.typeGroupName type-group-name}
The name of the "type group" that the type belongs to, e.g. "Task".
{@ant.typeGroupSubdir dir-name}
The name of the subdirectory that contains the documentation of all ANT types of the type group; e.g. "tasks".
{@ant.typeGroupHeading text}
The heading to display above the list of types; e.g. "Tasks".
{@ant.typeTitleMf message-format}
The message format to use to render the heading on each type details page; e.g. "Task &quot;&lt;{0}&gt;&quot;"
{@ant.typeHeadingMf message-format}
The message format to use to render the title (i.e. the tooltip) of the heading on each type details page; e.g. "Task &amp;quot;&lt;code>&lt;{0}&gt;&lt;/code>&amp;quot;"
{@ant.group group-name}
Attributes (or subelements) with equal group-name are grouped, and the group-name is rendered as a heading above the group.
{@ant.subelementOrder inheritedFirst}
Enforces that the subelements inherited from superclasses appear before the non-inherited. The default is that the subelements in their "natural" order.

Features[edit]

Basics[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

The doclet JAR file is here.

Find the source code for the doclet here.

Change Log[edit]

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[edit]

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.