First pass at XDoclet generation of Ant task documentation.

(sorry for the multiple commits, still getting a lock error on big commit attempts)


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271570 13f79535-47bb-0310-9956-ffa450edef68

proposal/xdocs/build.xml

@@ -0,0 +1,69 @@
+<?xml version="1.0" ?>
+<project name="XDoclet" default="gen">
+
+  <property name="log4j.jar" location="../../lib/optional/log4j.jar"/>
+  <property name="xdoclet.jar" location="lib/xdoclet.jar"/>
+
+  <property name="src.dir"
+            location="../../src/main/org/apache/tools/ant/taskdefs"/>
+  <property name="src.root"
+            location="../../src/main"/>
+  <property name="build.dir" location="build"/>
+  <property name="gen.dir" location="${build.dir}/gen"/>
+
+  <property name="template.dir" location="templates"/>
+  <property name="defaults.properties.template"
+            location="${template.dir}/defaults_properties.template"/>
+  <property name="xdoc.template"
+            location="${template.dir}/task_xdoc.template"/>
+
+
+  <path id="xdoclet.classpath">
+    <pathelement location="${log4j.jar}"/>
+    <pathelement location="${xdoclet.jar}"/>
+
+    <!-- javadoc is needed -->
+    <pathelement path="${java.class.path}"/>
+    <pathelement location="${build.dir}"/>
+  </path>
+
+  <taskdef name="document"
+           classname="xdoclet.doc.DocumentDocletTask"
+           classpathref="xdoclet.classpath"/>
+
+  <target name="init">
+    <mkdir dir="${build.dir}" />
+    <mkdir dir="${gen.dir}" />
+  </target>
+
+
+  <target name="clean">
+    <delete dir="${build.dir}"/>
+  </target>
+
+  <target name="compile" depends="init">
+    <javac srcdir="src" destdir="${build.dir}"
+           debug="true" classpathref="xdoclet.classpath"/>
+  </target>
+
+  <target name="gen" depends="compile">
+    <delete dir="${gen.dir}"/>
+
+    <document sourcepath="${src.root}"
+              destdir="${gen.dir}"
+              classpathref="xdoclet.classpath">
+      <fileset dir="${src.dir}">
+        <include name="*.java" unless="class.name"/>
+        <include name="${class.name}.java" if="class.name"/>
+      </fileset>
+      <template templateFile="${defaults.properties.template}"
+                destinationfile="defaults.properties"/>
+<!--       <template templateFile="${xdoc.template}"
+                destinationfile="{0}.xml" extent="concrete-type"/> -->
+      <template subTaskClassName="org.apache.tools.ant.xdoclet.AntSubTask"
+                templateFile="${xdoc.template}"
+                destinationfile="{0}.xml" extent="concrete-type"/>
+    </document>
+  </target>
+</project>
+

proposal/xdocs/lib/LICENSE.xdoclet.txt

@@ -0,0 +1,26 @@
+ Copyright (c) 2000-2002, XDoclet team
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without modification, 
+ are permitted provided that the following conditions are met:
+
+ Redistributions of source code must retain the above copyright notice, this list 
+ of conditions and the following disclaimer.
+
+ Redistributions in binary form must reproduce the above copyright notice, this list 
+ of conditions and the following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ Neither the name of the XDoclet team nor the names of its contributors may be used 
+ to endorse or promote products derived from this software without specific prior
+ written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY 
+ EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
+ SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
+ EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+ TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

proposal/xdocs/src/org/apache/tools/ant/taskdefs/Test.java

@@ -0,0 +1,67 @@
+/*
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2002 The Apache Software Foundation.  All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ *    any, must include the following acknowlegement:
+ *       "This product includes software developed by the
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowlegement may appear in the software itself,
+ *    if and wherever such third-party acknowlegements normally appear.
+ *
+ * 4. The names "The Jakarta Project", "Ant", and "Apache Software
+ *    Foundation" must not be used to endorse or promote products derived
+ *    from this software without prior written permission. For written
+ *    permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ *    nor may "Apache" appear in their names without prior written
+ *    permission of the Apache Group.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ */
+package org.apache.tools.ant.taskdefs;
+
+import org.apache.tools.ant.Task;
+
+/**
+ * @ant:task name="test"
+ */
+public class Test {
+    private String value;
+    
+    public void setValue (String value) {
+        this.value = value;
+    }
+}

proposal/xdocs/templates/defaults_properties.template

@@ -0,0 +1,5 @@
+<XDtTagDef:tagDef namespace="Ant" handler="org.apache.tools.ant.xdoclet.AntTagsHandler"/>
+<!-- @todo: add forAllTasks -->
+<XDtClass:forAllClasses>
+  <XDtAnt:taskName/>=<XDtClass:fullClassName/>
+</XDtClass:forAllClasses>

proposal/xdocs/templates/task_xdoc.template

@@ -0,0 +1,42 @@
+<XDtTagDef:tagDef namespace="Ant" handler="org.apache.tools.ant.xdoclet.AntTagsHandler"/>
+
+<task name="<XDtAnt:taskName/>" classname="<XDtClass:fullClassName/>">
+
+  <short-description><![CDATA[<XDtClass:firstSentenceDescription/>]]></short-description>
+  <long-description>
+    <![CDATA[<XDtClass:classComment no-comment-signs="true"/>]]>
+  </long-description>
+
+  <structure>
+
+    <XDtAnt:forAllAttributes>
+      <attribute name="<XDtMethod:propertyName/>" type="<XDtParameter:forAllMethodParams><XDtParameter:methodParamType/></XDtParameter:forAllMethodParams>">
+        <description><![CDATA[
+          <XDtMethod:methodComment no-comment-signs="true"/>
+        ]]></description>
+      </attribute>
+    </XDtAnt:forAllAttributes>
+
+    <XDtAnt:forAllElements>
+      <element name="<XDtAnt:elementName/>">
+        <description><![CDATA[
+          <XDtMethod:methodComment no-comment-signs="true"/>
+        ]]></description>
+      </element>
+    </XDtAnt:forAllElements>
+
+    <!-- @todo: wrap setCurrentMethod inside AntTagsHandler -->
+    <XDtMethod:setCurrentMethod name="addText" parameters="java.lang.String">
+      <body>
+        <description><![CDATA[
+          <XDtMethod:methodComment no-comment-signs="true"/>
+        ]]></description>
+      </body>
+    </XDtMethod:setCurrentMethod>
+
+  </structure>
+
+    <!-- merge point for samples? -->
+</task>
+
+