You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by le...@apache.org on 2004/05/05 23:27:00 UTC
cvs commit: jakarta-commons-sandbox/attributes/site/xdocs documenting.xml validator.xml
leosutic 2004/05/05 14:27:00
Added: attributes/site/xdocs documenting.xml validator.xml
Log:
Adding documentation of the Taglet and the validation task.
Revision Changes Path
1.1 jakarta-commons-sandbox/attributes/site/xdocs/documenting.xml
Index: documenting.xml
===================================================================
<?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-SNAPSHOT.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-SNAPSHOT.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-SNAPSHOT.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-SNAPSHOT.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-SNAPSHOT.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>
1.1 jakarta-commons-sandbox/attributes/site/xdocs/validator.xml
Index: validator.xml
===================================================================
<?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 - Validating Attributes at Compile-Time</title>
</properties>
<body>
<section name="Why?">
</section>
<section name="The attribute-validator Task">
</section>
<section name="Writing Your Own Validation Rules">
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org