Taglets Collection

This user guide section deals with the a more advanced usage of the Taglets Collection.
You will shortly see how to tweak JavaDoc output and how to configure some of the taglets properties.

Configuration

What follows is a short overview of some of the configuration options of the Taglets Collection.

To simplify build it uses Apache Ant, to see a sample that also lists commandline options for JavaDoc please check out the Simple Usage section.

In contrast to the simple demo this extended demo makes use of:

• Configuration of the predefined @adm tag.
• Mandatory use of @since (if omitted a warning is generated).
• Custom headers and footers that include a logo.
• Inclusion of a favourites icon in the docu generated.

Output

Before starting out with the configuration you might want to have a look at what we are going to create in the extended demo:

Do not be surprised if you look at the JavaDoc generated, I tried to make some Java/Chocolate theme. Well, ... you'll at least get the idea on how to customize the output of JavaDoc like this ...

Apache Ant Configuration

Let's first configure the build file build.xml. We will change the javadoc call from the simple demo to include additional features:

• Include an overview page (line 3).
• Set a window title for the generated JavaDoc (line 5).
• Show how to set commandline arguments for the Taglets Collection (line 6, set it to 'true' to obtain some verbose output).
• Set the title of the JavaDoc generated (lines 8-12).
• Add a page header that includes the taglets logo (lines 13-20, note that the HTML is escaped, {@docRoot} gets expanded to the root directory of the documentation generated).
• Add a page footer that includes the taglets logo (lines 21-27, HTML is escaped again, {@docRoot} gets expanded to the root directory of the documentation generated).
• At the bottom we add information blurp that includes the generation timestamp (lines 28-39, HTML is escaped again, the Ant property ${timestamp} is used in the usual manner).
• Add the rsrc directory as an additional taglet path entry (lines 40-46, this enables the Taglets Collection to load additional configuration files from this directory).

 001 
 002 
 003 
 004 
 005 
 006 
 007 
 008 
 009 
 010 
 011 
 012 
 013 
 014 
 015 
 016 
 017 
 018 
 019 
 020 
 021 
 022 
 023 
 024 
 025 
 026 
 027 
 028 
 029 
 030 
 031 
 032 
 033 
 034 
 035 
 036 
 037 
 038 
 039 
 040 
 041 
 042 
 043 
 044 
 045 
 046 
 047 
 048 

 <javadoc
   destdir="doc"
   overview="src/overview.html"
   private="true"
   windowtitle="Taglets Collection Extended Demo API Specification"
   additionalparam="-J-DTaglets.verbose=false"
 >
   <!-- Use a nice documentation title -->
   <doctitle>
     Taglets Collection<br>
     Extended Demo API Specification
   </doctitle>
   <!-- Create a header that contains the taglets logo -->
   <!-- Note the use of the {@docRoot} tag to link to the logo -->
   <header>
     &lt;img
       src=&quot;{@docRoot}/resources/logo.gif&quot; 
       width=&quot;88&quot; height=&quot;40&quot; border=&quot;0&quot;
     &gt;
   </header>
   <!-- Same for the footer -->
   <footer>
     &lt;img 
       src=&quot;{@docRoot}/resources/logo.gif&quot; 
       width=&quot;88&quot; height=&quot;40&quot;
     &gt;
   </footer>
   <!-- Include a timestamp at the bottom of the docu generated -->
   <!-- Note the use of ${timestamp} which was created by the -->
   <!-- <tstamp> task at the start of this target -->
   <bottom>
     &lt;p align=&quot;right&quot;&gt;
       &lt;font class=&quot;NavBarFont1&quot; size=&quot;-2&quot;&gt;
         Taglets Collection&lt;br&gt;
         Extended JavaDoc Demo&lt;br&gt;
         ${timestamp}
       &lt;/font&gt;
     &lt;/p&gt;
   </bottom>
   <!-- Include the 'rsrc' directory on the taglets path to include -->
   <!-- the 'taglets.properties' configuration as well as all binaries -->
   <!-- used by the configuration in the shutdown tasks -->
   <taglet
     name="net.sourceforge.taglets.Taglets"
     path="rsrc:../../taglets.jar"
   />
   <fileset dir="src" includes="**/*.java"/>
 </javadoc>

The taglets configuration directory rsrc that was added to the classpath of the taglet contains the extended taglets configuration as well as binary files that are used by this configuration:

Taglets Configuration

The Taglets Collection supports several configuration files and merges them together. In this example we make use of the fact that the Taglets Collection merges the configuration found in file /taglets.properties on the classpath with the default uration.

Anything defined in the /taglets.properties configuration file on the classpath supercedes the settings in the default configuration.

For more information about nested configuration files check out the Configuration subsection of the description of the default configuration in the user guide.

The configuration file for the extended demo looks defines the following features and overrides:

• Configuration of the predefined @adm tag (lines 8-11).
• All executable member documentation generated should have a mandatory @since tag, if it is missing a warning is generated (lines 13-14, override of default configuration).
• Use of a custom stylesheet (lines 20-21, override of default configuration).
• Adds additional resources to be copied to the documentation generated (lines 23-29).
• Modification of the documentation generated to include a favourites icon using a regular expression file replacer (lines 31-36, note that ${docRoot} gets replaced by the output directory).

 001 
 002 
 003 
 004 
 005 
 006 
 007 
 008 
 009 
 010 
 011 
 012 
 013 
 014 
 015 
 016 
 017 
 018 
 019 
 020 
 021 
 022 
 023 
 024 
 025 
 026 
 027 
 028 
 029 
 030 
 031 
 032 
 033 
 034 
 035 
 036 

 # Taglets Configuration for the extended JavaDoc demo.
 # ====================================================


 # Default Tag Configuration
 # -------------------------

 # Parameters for the @adm tag.
 Taglets.taglet.adm.params.maintainer.name= Some Body
 Taglets.taglet.adm.params.maintainer.mail= some.body@some.where.org
 Taglets.taglet.adm.params.maintainer.project= Taglets Demo

 # All Taglets sources should make use of @since.
 Taglets.taglet.since.mandatory= true


 # Shutdown Taglets
 # ----------------

 # We are using a custom stylesheet to make things fancy.
 Taglets.shutdown.javadoc-stylesheet-copy.files= stylesheet.css

 # Copy the demo logo to the resource directory, this is used in the
 # header and footer of the documentation generated.
 # (The todir listed below is relative to the JavaDoc output directory.)
 Taglets.shutdown.logo-copy= net.sourceforge.taglets.simple.shutdown.FileCopier
 Taglets.shutdown.logo-copy.todir= resources
 Taglets.shutdown.logo-copy.files= \
   logo.gif, show-off.gif, favicon.ico, beans.gif, inherit.gif

 # Fixup the favourites icon in the docu generated.
 Taglets.shutdown.favicon-fixup= net.sourceforge.taglets.simple.shutdown.RegexReplacer
 Taglets.shutdown.favicon-fixup.files= **/*.html
 Taglets.shutdown.favicon-fixup.token.0= </TITLE>
 Taglets.shutdown.favicon-fixup.value.0= </TITLE>\
   <link rel="shortcut icon" href="${docRoot}/resources/favicon.ico"/>

For a description of the predefined tags as well as more information on how to configure them please refer to the Predefined Tags subsection of the default configuration.

The "shutdown taglets" are described in the Shutdown Taglets subsection of the user guide that describes the default configuration.

Custom Taglets

Now that we have seen a sneak preview on how to configure the Taglets Collection and how to tweak JavaDoc using Ant to produce an enhanced documentation it is time to move on and define some custom tags and create a "Simple Taglet" in Java source.

The next section Custom Taglets gives a short introduction to creating custom taglets and adding new tags using the taglets configuration files.