Ant Documentation and XML Tasks

You can say which sources to document in several ways, and the result is the union of everything you specify:

If you mix sourcepath with a packageset that points at the same directory, excludepackagenames does not apply unless it agrees with the packageset’s own excludes; the manual calls this out because the union is easy to forget.

The tidepool-model records Height, Station, Constituent and TideEvent carry a one-line class comment. Height also uses a custom block tag, @tidepool.units. The target below documents the whole package, registers that tag, adds a heading, and groups the package on the overview page:

Running ant -q javadoc (the -q flag hides the per-file Generating … lines in this listing):

Source: Ant manual, javadoc

The task has many more attributes than the example uses. The ones that matter most, from the manual:

Some attributes and names are kept only for compatibility: old has no effect unless an external javadoc older than JDK 1.4 is used, and the task name javadoc2 is an alias that the manual says will be removed.

A nested group splits the overview page’s package table. Its packages list is colon-separated; a nested form with title and package children is needed when a title contains a space or comma. A nested tag registers a custom block tag: name, description, scope (a comma-separated subset of overview, packages, types, constructors, methods, fields, or all) and enabled. A tag with a dir attribute behaves as an implicit fileset whose files hold one tag definition per line. A nested taglet names a taglet class (name) and the path to load it from. A nested doclet swaps the whole doclet and takes param children. Taglets and doclets are ordinary javadoc extensions that run in the forked javadoc JVM, so they need nothing from Ant itself; only their class path (path, docletpath) has to be right.

A strict documentation build is the usual reason to set failonwarning="true". The build above is the trap: it has failonwarning="true", printed 11 warnings and still said BUILD SUCCESSFUL. The check in Ant 1.10.18 looks for the summary line with the regular expression (\d) warning[s]?$ applied with String.matches, which accepts exactly one digit. A run that reports 1 to 9 warnings fails the build; a run that reports 10 or more matches nothing and passes. The source at the 1.10.18 tag confirms it, and the two builds below show both sides on the same sources.

First, one warning (an unregistered tag, with the missing-@param checks switched off by -Xdoclint:-missing):

Registering the tag fixes it, and the build is quiet and green:

The practical lessons: do not rely on failonwarning as a gate when a project can produce ten or more warnings. Use -Xdoclint options to switch off the checks you do not want (as above) so that the count stays low, and check the log yourself if the gate matters. The gap is in the pattern Ant uses, not in your build file.

Source: Ant manual, javadoc; the check itself is in Javadoc.java at the rel/1.10.18 tag (the JavadocOutputStream class).

Since Ant 1.10.6 the task understands the module system: modulesourcepath, modulepath and their …ref forms, plus modulenames or nested module elements. A throwaway copy of the model with a module-info.java (module io.tidepool.model, exporting the one package) is documented like this:

The output goes to build/api-module/io.tidepool.model/…, one subdirectory per module. Dependencies on other modules (requires) are found through modulepath, which takes the directories or JARs of the other modules.

Source: Ant manual, javadoc

In the other tools: Maven runs maven-javadoc-plugin (goal javadoc:javadoc, configured under Site and Reporting in the Maven part of this section) and Gradle’s java plugin adds a javadoc task, covered on Java Projects. Both build the argument list for you; Ant gives you every flag and no defaults.

The stylesheet xml/stations.xsl lists each station, preceded by a heading taken from the heading parameter:

Source: Ant manual, xslt (style)

The target below calls xslt twice in a row with the same inputs, then calls style with force="true":

The second xslt produced no output at all: the target was newer than both the document and the stylesheet, so the task skipped it. force="true" made the style call run again, and the deprecation warning appears only for the old name.

Source: Ant manual, xslt (style)

In the other tools: Maven has no XSLT in the core; the Mojo xml-maven-plugin provides a transform goal. Gradle has no XSLT task either; a build script can use the JDK’s javax.xml.transform directly or call Ant’s xslt through the Ant integration.

xmlvalidate checks that files are well formed or valid. It uses the JAXP SAX2 parser (normally the JDK’s built-in Xerces) and accepts file or a nested fileset. lenient="true" reduces the check to well-formedness; warn logs parser warnings; failonerror defaults to true; classname and classpath select another parser. Nested dtd, xmlcatalog, attribute (parser features such as http://xml.org/sax/features/validation) and property (parser properties, for example the Xerces external-noNamespaceSchemaLocation that points at an XSD) configure it.

The manual flags one trap: the JAXP parser Ant creates is not namespace aware, so a document that uses a xsi:noNamespaceSchemaLocation attribute needs <attribute name="http://xml.org/sax/features/namespaces" value="true"/>. That is also why the manual recommends schemavalidate for XSD validation.

Well-formedness check, run against xml/stations.xml:

Source: Ant manual, xmlvalidate

schemavalidate extends xmlvalidate for W3C XML Schema. It makes the parser validating, namespace aware and schema-aware by itself. A schema for documents without a namespace comes from noNamespaceFile or noNamespaceURL; namespaced schemas are bound with nested schema elements (namespace plus file or url). fullchecking (slow but strict) defaults to true, and disableDTD turns DTD support off. Only SAX2 parsers are allowed.

The schema xml/stations.xsd requires four attributes on every station, with latitude and longitude typed xs:decimal. A valid file passes silently:

Running the same task on xml/stations-bad.xml, where one station has latitude="north", fails with the parser’s messages and a generic summary line:

The 3:81 is line and column in the data file; the cvc-… codes come from the parser, so you can look them up in the XML Schema specification. The summary line names the file but not the cause, so always read the lines above it.

Source: Ant manual, schemavalidate

The manual also shows a presetdef (see Macros & Presets) that wraps schemavalidate with a set of schema bindings, so that a project validates SOAP or WSDL files with one short name. That example needs the schema files from W3C and is not run here.

echoxml writes the XML nested inside it, as XML, to the log or to a file (file, append). Since Ant 1.8 the namespacePolicy attribute (ignore, the default, elementsOnly or all) controls how namespaces are written. It is the simplest way to generate a build file or a configuration file from a template without <concat> and escaping.

Source: Ant manual, echoxml

xmlproperty loads the values of an XML file into properties: the element path becomes the property name. By default it does no processing, so a reference such as ${foo} inside the file is not expanded. The attributes that change the result:

With this file, xml/build-info.xml:

the target reads it three ways:

The first call keeps the default names, where an attribute is written element(attribute). The second collapses attributes into dotted names. Its last item shows that with keepRoot="false" the root’s own attribute (release) produced no property, so the reference is left as written. The third uses semanticAttributes: <version value="1.2.0"/> becomes the single property s.version.

Properties are immutable once set (see Properties), so a second xmlproperty with the same names changes nothing; use a prefix, as above, when you read the same file twice.

Source: Ant manual, xmlproperty