Editing ANT doclet
Jump to navigation
Jump to search
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.
Latest revision | Your text | ||
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 [[ | The motivation for writing this doclet is to ease the maintenance of the documentation for the [[Ant-contrib.unkrig.de]] 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: | |||
< | ;<code>-d</code> ''directory'' | ||
;<code>-windowtitle</code> ''window-title'' | |||
;<code>-doctitle</code> ''document-title'' | |||
;<code>-header</code> ''header'' | |||
;<code>-footer</code> ''footer'' | |||
;<code>-top</code> ''top'' | |||
;<code>-bottom</code> ''bottom'' | |||
;<code>-notimestamp true|<u>false</u></code> | |||
;<code>-link</code> ''url-or-file'' | |||
;<code>-linkoffline</code> ''url-or-file'' ''package-list-url-or-file'' | |||
:Same as for the standard JAVADOC doclet | |||
;<code>-antlib-file</code> ''file'' | |||
:The antlib file of the antlib to document; defaults to "antlib.xml". | |||
the | |||
;<code>-theme JAVA7|<u>JAVA8</u></code> | |||
:The style of the generated pages. | |||
== Features == | == Features == | ||
Line 123: | Line 31: | ||
=== Basics === | === Basics === | ||
The doclet parses the | The doclet parses the ANTLIB file 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>". | 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>". | ||
Line 131: | Line 39: | ||
=== Related attributes === | === 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. | 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. | ||
=== Grouping of 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". | |||
, | 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]. | ||
== Resources == | == Resources == | ||
The doclet JAR file is [ | The doclet JAR file is [http://doclet.unkrig.de/ant/download/ here]. | ||
The change log is [http://doclet.unkrig.de/ant/CHANGELOG.txt here]. | |||
Find the source code for the doclet [https://svn.code.sf.net/p/loggifier/code/trunk/de.unkrig.doclet.ant here]. |