[PATCH]: enhanced javadoc task

Patrick Chanezon 14 Mar 2000 03:12:58 -0000

Hi ant users and developers,

I enhanced the javadoc task in order to make full use of some javadoc
features as descibed in
http://jakarta.apache.org/bugs/show_bug.cgi?id=64


which means:
* support for multiple link options
* support for multiple group options
* support for the @ argument

 - link and linkoffline: you can now list more than one -link option,
using a ; separator in your link tag to separate the different lines
that will be generated
 - group: same remark, you can now list more than one -group option,
using a ; separator in your group tag. arguments are
groupheading;packagepattern:packagepattern:..
 - group: the syntax is "-group  groupheading
packagepattern:packagepattern:.."
 - the COMMAND LINE ARGUMENT FILE syntax: javadoc -d apidocs @packages
is now supported with the packagelist
tag this is how these options can be used in a build.xml file:

    <javadoc sourcepath="${src.dir}"
             destdir="${build.javadocs}"
             author="true"
             version="true"
             windowtitle="${Name} API"
             doctitle="${Name}"
             bottom="Copyright &#169; 2000 Apache Software Foundation.
All Rights Reserved."

link="http://java.sun.com/products/jdk/1.2/docs/api/;http://developer.java.sun.com/developer/products/xml/docs/api/";

             group="Ant Tools Packages;org.apache.tools.ant;Ant Task
Packages;org.apache.tools.ant.taskdefs"
             packageList="src/etc/packagelist.txt"
    />

I also attach a modified version of build.xml for ant and
packagelist.txt (you should put it in src/etc)
try ant javadocs on your ant tree with the patch and these 2 files, to
see the result.
And let me know if you like the separator syntax: allowing 2 attributes
with the same name would maybe be a better option, and an xml element
for groups, with 2 attributes. It would be more readable. If you prefer
this just let me know so that I can implement it.

I hope you'll like the improvement

P@

--
Patrick Chanezon, Vortex - Portal/EServices Technical Lead
Netscape Communications Corp. - http://people.netscape.com/chanezon/
Opinions are my own.

"Ouais, n'emp�che qu'� la retraite de Russie, c'est les mecs qu'�taient
� la tra�ne qu'ont �t� repass�s..." - Michel Audiard - Les Tontons
Flingueurs

Index: Javadoc.java
===================================================================
RCS file: 
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java,v
retrieving revision 1.7
diff -u -r1.7 Javadoc.java
--- Javadoc.java        2000/03/03 14:15:42     1.7
+++ Javadoc.java        2000/03/14 03:02:11
@@ -75,6 +75,21 @@
  *
  * @author Jon S. Stevens <a href="mailto:[EMAIL PROTECTED]">[EMAIL 
PROTECTED]</a>
  * @author Stefano Mazzocchi <a href="mailto:[EMAIL PROTECTED]">[EMAIL 
PROTECTED]</a>
+ * @author Patrick Chanezon <a href="mailto:[EMAIL PROTECTED]">[EMAIL 
PROTECTED]</a>
+ * I enhanced the task as described in 
http://jakarta.apache.org/bugs/show_bug.cgi?id=64
+ * which means:
+ * support for multiple link options
+ * support for multiple group options
+ * support for @
+ * - link and linkoffline: you can now list more than one -link option, using 
a ; separator in your link tag to separate the different lines that will be 
generated
+ * - group: same remark, you can now list more than one -group option, using a 
; separator in your group tag. arguments are 
groupheading;packagepattern:packagepattern:..
+ * - group: the syntax is "-group  groupheading  
packagepattern:packagepattern:.."
+ * - the COMMAND LINE ARGUMENT FILE syntax: javadoc -d apidocs @packages is 
now supported with the packagelist tag
+ * this is how these options can be used in a build.xml file:
+ * 
link="http://java.sun.com/products/jdk/1.2/docs/api/;http://java.sun.com/products/servlet/2.2/javadoc/;http://developer.java.sun.com/developer/products/xml/docs/api/";
+ * group="Group1 Packages;com.blahblah.pack1*:com.blahblah.pack2*;Group2 
Packages;com.blahblah.pack3*:com.blahblah.pack4*"
+             packageList="${src.dir}/doc/packagelist.txt"
+
  */
 
 public class Javadoc extends Exec {
@@ -119,6 +134,8 @@
     private File helpfile = null;
     private String docencoding = null;
     private Vector compileList = new Vector(10);
+    private String packageList = null;
+    private static final String multipleArgumentSeparator  = ";";
 
     public void setSourcepath(String src) {
         sourcePath = project.translatePath(src);
@@ -359,16 +376,34 @@
                 argList.addElement(bottom);
             }
             if (link != null) {
-                argList.addElement("-link");
-                argList.addElement(link);
+                // if no separator in the link list, we just add it to the 
arguments
+                if (link.lastIndexOf(multipleArgumentSeparator) < 0) {
+                    argList.addElement("-link");
+                    argList.addElement(link);
+                }
+                else {
+                    generateMultipleArgs("link", link, argList, 1);
+                }
             }
             if (linkoffline != null) {
-                argList.addElement("-linkoffline");
-                argList.addElement(linkoffline);
+                // if no separator in the link list, we just add it to the 
arguments
+                if (linkoffline.lastIndexOf(multipleArgumentSeparator) < 0) {
+                    argList.addElement("-linkoffline");
+                    argList.addElement(linkoffline);
+                }
+                else {
+                    generateMultipleArgs("linkoffline", linkoffline, argList, 
1);
+                }
             }
             if (group != null) {
-                argList.addElement("-group");
-                argList.addElement(group);
+                // if no separator in the link list, we just add it to the 
arguments
+                if (link.lastIndexOf(multipleArgumentSeparator) < 0) {
+                    argList.addElement("-group");
+                    argList.addElement(group);
+                }
+                else {
+                    generateMultipleArgs("group", group, argList, 2);
+                }
             }
             if (stylesheetfile != null) {
                 argList.addElement("-stylesheetfile");
@@ -403,6 +438,9 @@
             }
         }
 
+        if (packageList != null) {
+            argList.addElement("@" + packageList);
+        }
         project.log("Javadoc args: " + argList.toString(), "javadoc", 
project.MSG_VERBOSE);
 
         project.log("Javadoc execution", project.MSG_INFO);
@@ -446,6 +484,24 @@
                     argList.addElement(pack);
                     break;
                 }
+            }
+        }
+    }
+
+    /**
+     * Given a list of arguments separated by ; generates multiple argName 
arguments
+     * this is useful to pass multiple group and link arguments to javadoc
+     */
+    private void generateMultipleArgs(String argName, String argValue, Vector 
argList, int Dimension) {
+        project.log("Generating multiple " + argName + " arguments", 
project.MSG_INFO);
+        project.log("argValue = " + argValue, project.MSG_VERBOSE);
+
+        StringTokenizer tok = new StringTokenizer(argValue, 
multipleArgumentSeparator, false);
+        while (tok.hasMoreTokens()) {
+            argList.addElement("-" + argName);
+            for (int i = 0; i < Dimension; ++i)
+            {
+                argList.addElement(new String(tok.nextToken().trim()));
             }
         }
     }

<?xml version="1.0"?>

<!-- ======================================================================= -->
<!-- Ant own build file                                                      -->
<!-- ======================================================================= -->

<project name="Ant" default="main" basedir=".">

  <target name="init">
    <property name="Name" value="Ant"/>
    <property name="name" value="ant"/>
    <property name="version" value="1.0-rc1"/>

    <property name="ant.home" value="."/>
    <property name="bin.dir" value="bin"/>
    <property name="src.bin.dir" value="src/bin"/>
    <property name="src.dir" value="${basedir}/src/main"/>
    <property name="lib.dir" value="lib"/>
    <property name="docs.dir" value="docs"/>
    <property name="build.dir" value="build"/>
    <property name="build.classes" value="build/classes"/>
    <property name="build.javadocs" value="build/javadocs"/>
    <property name="ant.dist.dir" value="dist"/>

    <property name="classpath" value="lib/xml.jar"/>
<!--    <property name="packages" value="org.apache.tools.*"/>   -->
    <property name="manifest" value="src/etc/manifest"/>

    <property name="build.compiler" value="classic"/>

    <!-- Give user a chance to override without editing this file 
         (and without typing -D each time it compiles it -->
    <property file="${user.home}/.ant.properties" />
  </target>

  <!-- =================================================================== -->
  <!-- Prepares the build directory                                        -->
  <!-- =================================================================== -->
  <target name="prepare" depends="init">
    <mkdir dir="${build.dir}"/>
  </target>

  <!-- =================================================================== -->
  <!-- Compiles the source code                                            -->
  <!-- =================================================================== -->
  <target name="compile" depends="prepare">
    <mkdir dir="${build.classes}"/>
    <javac srcdir="${src.dir}"
           destdir="${build.classes}"
           classpath="${classpath}"
           debug="on"
           deprecation="on"
           optimize="on"
    />
  </target>

  <!-- =================================================================== -->
  <!-- Creates the jar archive                                             -->
  <!-- =================================================================== -->
  <target name="jar" depends="compile">
    <jar jarfile="${lib.dir}/${name}.jar"
         basedir="${build.classes}"
         includes="org/**"
         manifest="${manifest}"
    />
  </target>

  <!-- =================================================================== -->
  <!-- Creates the binary structure                                        -->
  <!-- =================================================================== -->
  <target name="main" depends="jar">
     <mkdir dir="${bin.dir}"/>
     <copydir src="${src.bin.dir}" dest="${bin.dir}"/>
     <chmod perm="+x" src="${bin.dir}/ant"/>
     <chmod perm="+x" src="${bin.dir}/antRun"/>
     <fixcrlf srcdir="${bin.dir}" includes="ant,antRun" cr="remove"/>
     <fixcrlf srcdir="${bin.dir}" includes="*.bat" cr="add"/>
  </target>

  <!-- =================================================================== -->
  <!-- Creates the API documentation                                       -->
  <!-- =================================================================== -->
  <target name="javadocs" depends="prepare">
    <mkdir dir="${build.javadocs}"/>
<!--    <javadoc packagenames="${packages}"   -->
    <javadoc sourcepath="${src.dir}"
             destdir="${build.javadocs}"
             author="true"
             version="true"
             windowtitle="${Name} API"
             doctitle="${Name}"
             bottom="Copyright &#169; 2000 Apache Software Foundation. All Rights Reserved."
             link="http://java.sun.com/products/jdk/1.2/docs/api/;http://developer.java.sun.com/developer/products/xml/docs/api/";
             group="Ant Tools Packages;org.apache.tools.ant;Ant Task Packages;org.apache.tools.ant.taskdefs"
             packageList="src/etc/packagelist.txt"
    />
  </target>

  <!-- =================================================================== -->
  <!-- Creates the distribution                                            -->
  <!-- =================================================================== -->
  <target name="dist" depends="main,jar,javadocs">
     <mkdir dir="${ant.dist.dir}"/>
     <mkdir dir="${ant.dist.dir}/bin"/>
     <mkdir dir="${ant.dist.dir}/lib"/>
     <mkdir dir="${ant.dist.dir}/docs"/>
     <mkdir dir="${ant.dist.dir}/docs/api"/>
     <mkdir dir="${ant.dist.dir}/src"/>

     <copydir src="${src.dir}" dest="${ant.dist.dir}/src"/>
     <copydir src="${lib.dir}" dest="${ant.dist.dir}/lib"/>

     <copyfile src="build.xml" dest="${ant.dist.dir}/lib/build.xml"/>
     <copydir src="src/bin" dest="${ant.dist.dir}/bin"/>
     <copydir src="${docs.dir}" dest="${ant.dist.dir}/docs"/>
     <copydir src="${build.javadocs}" dest="${ant.dist.dir}/docs/api"/>

     <chmod perm="+x" src="${ant.dist.dir}/bin/ant"/>
     <chmod perm="+x" src="${ant.dist.dir}/bin/antRun"/>

     <copyfile src="README" dest="${ant.dist.dir}/README"/>
     <copyfile src="TODO" dest="${ant.dist.dir}/TODO"/>
     <copyfile src="LICENSE" dest="${ant.dist.dir}/LICENSE"/>
  </target>

  <!-- =================================================================== -->
  <!-- Packages the distribution with ZIP                                  -->
  <!-- =================================================================== -->
  <target name="dist-zip" depends="dist">
    <zip zipfile="${Name}-${version}.zip" basedir="${ant.dist.dir}" includes="**"/>
  </target>

  <!-- =================================================================== -->
  <!-- Packages the distribution with TAR-GZIP                             -->
  <!-- =================================================================== -->
  <target name="dist-tgz" depends="dist">
    <tar tarfile="${Name}-${version}.tar" basedir="${ant.dist.dir}" includes="**"/>
    <gzip zipfile="${Name}-${version}.tar.gz" src="${Name}-${version}.tar"/>
  </target>

  <!-- =================================================================== -->
  <!-- Cleans up generated stuff                                           -->
  <!-- =================================================================== -->
  <target name="clean" depends="init">
    <deltree dir="${build.dir}"/>
    <deltree dir="${ant.dist.dir}"/>
  </target>

  <!-- =================================================================== -->
  <!-- Total cleanup                                                       -->
  <!-- =================================================================== -->
  <target name="total-clean" depends="clean">
    <deltree dir="${bin.dir}"/>
    <delete file="${lib.dir}/${name}.jar"/>
    <delete file="${Name}-${version}.zip"/>
    <delete file="${Name}-${version}.tar"/>
    <delete file="${Name}-${version}.tar.gz"/>
  </target>

  <!-- in progress ! (may not work) -->

  <target name="get.snapshot" depends="init">
    <get src="http://jakarta.apache.org/build/tmp/ant/ant.src.zip"; dest="ant-src.zip" />
    <expand src="ant-src.zip" dest="." />
  </target>

  <target name="make.snapshot">
    <cvs cvsRoot=":pserver:[EMAIL PROTECTED]:/home/cvspublic"
         package="jakarta-ant"
         dest="."  />
    <zip zipfile="/www/jakarta.apache.org/builds/tmp/ant/ant.src.zip" basedir="." includes="jakarta-ant/**"/>
  </target>

</project>

org.apache.tools.ant
org.apache.tools.ant.taskdefs

begin:vcard 
n:Chanezon;Patrick
tel;fax:603.388-9565
tel;work:650.937.6605
x-mozilla-html:TRUE
org:<CENTER><A HREF="http://www.iplanet.com/";><IMG SRC="http://www.iplanet.com/images/header_images/logo.gif"; BORDER=0 </A></CENTER>;Vortex
version:2.1
email;internet:[EMAIL PROTECTED]
title:<I>Vortex - Portal/EServices Technical Lead</I>
note:<A HREF="http://people.netscape.com/chanezon/";><IMG SRC="http://people.netscape.com/chanezon/patrick_photo_identite.jpg"; BORDER=0 HEIGHT=70 WIDTH=49></A><BR>Have Fun with <A HREF="http://www.javasoft.com/";><IMG SRC="http://www.javasoft.com/images/logos/javalogo52x88.gif"; border="0" HEIGHT="88" WIDTH="52"></A><BR><hr><BR>
adr;quoted-printable:;;Netscape Communications Corp.=0D=0A501 E. Middlefield Road=0D=0ABuilding 6=0D=0AMV-025;Mountain View;CA;94043;USA
fn:Patrick Chanezon
end:vcard

[PATCH]: enhanced javadoc task

Reply via email to