Javadoc

This plugin provides javadoc generation targets.

Declaration

  <plugin name="javadoc">
    <attribute name="javadoc.set.list" value="application"/>
    <!-- Javadoc configuration for application set -->
    <attribute name="javadoc.application.access" value="protected"/>
    <attribute name="javadoc.application.doctitle">
<![CDATA[<h1>My Application Documentation</h1>]]></attribute>
    <attribute name="javadoc.application.windowtitle">My Application API</attribute>
  </plugin>

This declaration is an example of configuration for a javadoc generation of a module set called application.

An equivalent way of declared javadoc set attributes is:

  <plugin name="javadoc"
    xmlns:javadoc="antlib:ch.elca.el4ant.javadoc">
    <attribute name="javadoc.set.list" value="application"/>
    <!-- Javadoc configuration for application set -->
    <javadoc:config set="application">
      <javadoc:attribute name="access" value="protected"/>
      <javadoc:attribute name="doctitle">
<![CDATA[<h1>My Application Documentation</h1>]]></javadoc:attribute>
      <javadoc:attribute name="windowtitle">My Application API</javadoc:attribute>
    </javadoc:config>
  </plugin>

Usage

This plugin generates a javadoc per module set. A module can be registered in one or many sets thank to the set attribute. Please read details about module sets.

For more details about the javadoc plugin attributes, please read the javadoc Ant task documentation.

When used with the website plugin, javadoc are generated in the website.directory and a report entry is added in the project project page.

Targets

• javadoc generates all javadoc reports for the module sets declared in javadoc.set.list.
• javadoc.set generates the javadoc report for a specific module set.

Attributes

Global

If a javadoc attribute is not explicitly defined for a specific set, its value remains the default one. The upper case SET notation is used here to represent a module set name.

• javadoc.set.list is the list of module sets for which the javadoc target generates reports by default. Default value is the list of known module sets.
• javadoc.SET.destdir is the Ant javadoc destdir parameter. Default value is dist/javadoc/SET/ or javadoc/SET in website.directory when used with website plugin.
• javadoc.SET.PARAMETER is the Ant javadoc PARAMETER value for the set SET. For instance javadoc.myset.access is the Ant javadoc access parameter for myset and possibile values are private, protected, public. Default values for all parameters are given in the following table.

Parameter	Default value
access	private
author	true
bottom
breakiterator
charset
doctitle	Application API
docencoding
encoding
footer
header	Application API
helpfile
linksource
locale
maxmemory	128m
nodeprecated
nodeprecatedlist
nohelp
nonavbar
noindex
notree
packagenames	*
serialwarn
splitindex
stylesheetfile
use	true
verbose
version	true
windowtitle	Application API

When a parameter has a default value, its value can be changed with the attribute javadoc.default.PARAMETER.

The special parameter antelements can be used to pass xml blocks directly to the Ant javadoc task for the set, like the group element for example:

<attribute name="javadoc.el4ant.antelements">
  <![CDATA[<group title="Plugins">
    <package name="ch.elca.el4ant.*"/>
  </group>
  ]]>
</attribute>

Hooks

• pre.javadoc and post.javadoc called unconditionnaly
  • set is the current set
  • set.additonalparam can be appended to pass additional parameters to the javadoc command

Known issues

I get message No source files and no packages have been specified

The javadoc and javadoc.set targets may fail with the message: No source files and no packages have been specified.

This means the processed module set does not contain any source file. It may come from:

• an empty set: no module in the set
• modules without java/ directories (such as binary modules)
• modules with empty java/ directories

You can ignore this message. Only the report for the concerned set is not generated. The message will disappear as soon as at least one source file will be present in the module set.

I get warnings about unknown packages or classes from import statements

It is most likely the concerned classes are in modules in dependence but are not compiled. First run compile target and try again.

I can not create Javadoc with JDK1.5 if a module has Commons Attributes enabled

There is a bug in CATaglet class of Commons Attributes. Please replace existing jars with name commons-attributes-compiler-2.2.jar with the following http://el4.elca-services.ch/el4ant/jars/commons-attributes-compiler-2.2.jar or use EL4Ant version > 0.9.2 or upper.

Javadoc parameter bottom is wrong used on Windows

There is a bug that parameter bottom is taken as package name instead as html page bottom line. Further if the bottom parameter is long, javadoc generation will fail.

ToDo

• collect module docs directories
• support doc-file directories
• add parameters: group, overview, link.