Ant generates the document

Documents are required in any project. D ocumentation is critical to the maintenance of a project. U sing the built-in Javadoc tool makes it easier to build documents using Java. Ant makes this step even easier by generating documents on demand.

As you know, javadoc tools are highly flexible and allow for some configuration. A nt exposes these configuration options by using javadoc tasks. If you're not familiar with javadoc, we recommend that you take a look at the Java documentation tutorial first.

The following sections list the options for javadoc, which is most commonly used in Ant.

Property

The source includes three properties: the source path, the source path reference, or the source file.

• The source path points to the folder in which the source file is located, for example: the src folder.
• The source path reference (sourcepathref) points to a path referenced by the path property, for example: delegates.src.dir.
• Source files are used when you want to specify a separate file, such as specifying a comma-separated list.

The destination path is specified by using the destdir folder, such as build.dir.

You can filter javadoc tasks by specifying the name of the package that should be included. This can be done by using the packagenames property, which is a list of package files separated by commas.

You can filter the javadoc process to show only public, private, packaged, or protected classes and members. These can be done by using the private, public, package, and protected properties.

You can also tell the javadoc task to include author and version information by using the appropriate properties.

You can also use the group property to organize all packages together to make them easier to manipulate.

Bring the above together

Let's continue with our topic, Hello world fax app. Let's add a document target to our fax application project.

The following example is the javadoc task we use in our project. In this example, we specify javadoc to use src.dir as the source directory and doc as the target.

We also customize window titles, titles, and footer information that appears on the java document page.

In addition, we created three groups:

• Create a group for the utility class in the source folder.
• A group is created for the class of the user interface.
• Create a group for a database-related class.

You may notice that packet groups contain two packages -- faxapp.entity and faxapp.dao.

<target name = "generate-javadoc">
   <javadoc packagenames="faxapp.*" sourcepath="${src.dir}" 
      destdir = "doc" version = "true" windowtitle = "Fax Application">

      <doctitle><![CDATA[= Fax Application =]]></doctitle>

      <bottom>
         <![CDATA[Copyright © 2011. All Rights Reserved.]]>
      </bottom>

      <group title = "util packages" packages = "faxapp.util.*"/>
      <group title = "web packages" packages = "faxapp.web.*"/>
      <group title = "data packages" packages = "faxapp.entity.*:faxapp.dao.*"/>
   </javadoc>

   <echo message = "java doc has been generated!" />
</target>

Let's run the javadoc Ant task. It generates java document files and places them in the doc folder.

When the javadoc target is executed, it produces the following output:

>C:\>ant generate-javadoc
>Buildfile: C:\build.xml

>java doc has been generated!

>BUILD SUCCESSFUL
>Total time: 10.63 second

The java document file now appears in the doc folder.

Typically, javadoc files are part of a distribution or package target.