<?xml version="1.0"?>
<!--
=
= Copyright 2003-2004 The Apache Software Foundation
= 
= Licensed under the Apache License, Version 2.0 (the "License");
= you may not use this file except in compliance with the License.
= You may obtain a copy of the License at
= 
=     http://www.apache.org/licenses/LICENSE-2.0
= 
= Unless required by applicable law or agreed to in writing, software
= distributed under the License is distributed on an "AS IS" BASIS,
= WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
= See the License for the specific language governing permissions and
= limitations under the License.
=
-->
<document>
    
    <properties>
        <author email="commons-dev@jakarta.apache.org">Jakarta Commons Development Team</author>
        <title>Reference - Documenting with the Taglet</title>
    </properties>
    
    <body>
        <section name="What is a Taglet?">
            
            <p>A taglet is simply put a handler for a Javadoc tag, such as @author, @since and @param.</p>
            
            <source><![CDATA[/**
 * @since 1.2
 * @author Me
 */]]></source>
            
            <p>
                The taglet is then responsible for formatting the tag in the HTML output.
            </p>
        </section>
        
        <section name="How Do I Use It?">
            
            <p>
                We will go through the options below, but in short:
            </p>
            
            <source><![CDATA[javadoc 
    -J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=. 
    -tagletpath commons-attributes-compiler-2.2.jar
    -taglet org.apache.commons.attributes.javadoc.CATaglet 
    [source files]
]]></source>
            
            <p>
                From top to bottom, then, are the options specific for the Commons-Attributes taglet:
            </p>
            
            <subsection name="-J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources">
                <p>
                    Due to the way tags are used by Commons-Attributes, the Taglet must know which Java
                    files it will run on. This is caused by the Taglet API, which requires the Taglet to
                    specify exactly which tags it will handle. Since @@MyAttr() and @@MyOtherAttr() are
                    considered two different tags, the taglet must first scan the source files and compile
                    a list of all potential tag names.
                </p>
                
                <p>
                    This parameter is a semi-colon (Win32) or colon (Unix) separated list of files or directories
                    that will be used to create Javadocs. If you specify a directory, then all .java files in that
                    directory and any subdirectories are included.
                </p>
                
                <p>
                    Example:
                </p>
                
                <source><![CDATA[javadoc 
    ]]><b><![CDATA[-J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=/home/leo/java]]></b><![CDATA[ 
    -tagletpath commons-attributes-compiler-2.2.jar
    -taglet org.apache.commons.attributes.javadoc.CATaglet 
    [source files]
]]></source>
                
            </subsection>
            
            <subsection name="-tagletpath">
                <p>
                    This is simply the classpath for taglets. Include the commons-attributes-compiler JAR.
                </p>
                
                <p>
                    Example:
                </p>
                
                <source><![CDATA[javadoc 
    -J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=/home/leo/java
    ]]><b><![CDATA[-tagletpath commons-attributes-compiler-2.2.jar]]></b><![CDATA[
    -taglet org.apache.commons.attributes.javadoc.CATaglet 
    [source files]
]]></source>
                
            </subsection>
            
            <subsection name="-taglet">
                <p>
                    The fully-qualified class name of the taglet.
                </p>
                
                <p>
                    Example:
                </p>
                
                <source><![CDATA[javadoc 
    -J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=/home/leo/java
    -tagletpath commons-attributes-compiler-2.2.jar
    ]]><b><![CDATA[-taglet org.apache.commons.attributes.javadoc.CATaglet]]></b><![CDATA[ 
    [source files]
]]></source>
                
            </subsection>
            
            
        </section>
        
        <section name="Ant Usage">
            
            <p>
                Ant usage is similar to command line usage.
            </p>
            
            <source><![CDATA[<javadoc 
    destdir="${basedir}/javadoc/"
    additionalparam="-J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=${basedir}">
    <taglet
        name="org.apache.commons.attributes.javadoc.CATaglet"
        path="${ant.home}/lib/commons-attributes-compiler-2.2.jar"
    />
    <fileset dir="${basedir}/" includes="**/*.java" />
</javadoc>]]></source>
            
            <p>
                Note the need to:
            </p>
            
            <ul>
                <li>
                    <p>
                        Include an additionalparam option to specify location of source files.
                    </p>
                </li>
                <li>
                    <p>
                        Specify the path to the attribute compiler jar when specifying the taglet.
                        (Javadoc is a separate JVM and does not share classpaths with Ant.)
                    </p>
                </li>
            </ul>
            
            <p>
                After you've run the <a href="ant_demo.html">Ant Demo</a>, you can also type:
            </p>
            
            <source><![CDATA[# ant javadoc]]></source>
            
            <p>To generate Javadocs for the demo.</p>
        </section>
        
    </body>
    
</document>
