Return-Path: Mailing-List: contact ant-dev-help@jakarta.apache.org; run by ezmlm Delivered-To: mailing list ant-dev@jakarta.apache.org Received: (qmail 22494 invoked by uid 500); 29 Jun 2000 15:33:04 -0000 Delivered-To: apmail-jakarta-ant-cvs@apache.org Received: (qmail 22485 invoked by uid 1142); 29 Jun 2000 15:33:02 -0000 Date: 29 Jun 2000 15:33:02 -0000 Message-ID: <20000629153302.22482.qmail@locus.apache.org> From: conor@locus.apache.org To: jakarta-ant-cvs@apache.org Subject: cvs commit: jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional RenameExtensions.java conor 00/06/29 08:32:56 Modified: docs index.html src/main/org/apache/tools/ant BuildListener.java DirectoryScanner.java XmlLogger.java src/main/org/apache/tools/ant/taskdefs Javadoc.java src/main/org/apache/tools/ant/taskdefs/optional RenameExtensions.java Added: src/main/org/apache/tools/ant PathTokenizer.java Log: Update javadoc task to support multiple link and group options. Submitted by: Patrick Chanezon Revision Changes Path 1.34 +107 -11 jakarta-ant/docs/index.html Index: index.html =================================================================== RCS file: /home/cvs/jakarta-ant/docs/index.html,v retrieving revision 1.33 retrieving revision 1.34 diff -u -r1.33 -r1.34 --- index.html 2000/06/29 10:23:27 1.33 +++ index.html 2000/06/29 15:32:34 1.34 @@ -13,6 +13,7 @@

Jacques Bergeron (jacques.bergeron@dogico.com)
Stefan Bodewig (stefan.bodewig@megabit.net)
Patrick Chanezon (chanezon@netscape.com)
James Duncan Davison (duncan@x180.com)
Tom Dimock (tad1@cornell.edu)
Bill Kelly (bill.kelly@softwired-inc.com)

mypackage/p1

mypackage/p2

mypackage/p1/testpackage

Javadoc/Javadoc2

Description

Generates code documentation using the javadoc tool.

The source directory will be recursively scanned for Java source files to but -only those matching the inclusion rules will be passed to the javadoc tool. This +

The source directory will be recursively scanned for Java source files to process +but only those matching the inclusion rules will be passed to the javadoc tool. This allows wildcards to be used to choose between package names, reducing verbosity and management costs over time. This task, however, has no notion of -"changed" files, unlike the javac task, but it's -not used so frequently.

javac

This task works seamlessly between different javadoc versions (1.1 and 1.2), with the obvious restriction that the 1.2 attributes will be ignored if run in a 1.1 VM.

NOTE: since javadoc calls System.exit(), we cannot run javadoc inside the -same VM without breaking functionality. For this reason, this task always forks -the VM. But this is not a performance penalty since javadoc is normally a heavy -application and must be called just once.

NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the +same VM as ant without breaking functionality. For this reason, this task +always forks the VM. This overhead is not significant since javadoc is normally a heavy +application and will be called infrequently.

NOTE: the packagelist attribute allows you to specify the list of packages to +document outside of the Ant file. It's a much better practice to include everything +inside the build.xml file. This option was added in order to make it easier to +migrate from regular makefiles, where you would use this option of javadoc. +The packages listed in packagelist are not checked, so the task performs even +if some packages are missing or broken. Use this option if you wish to convert from +an existing makefile. Once things are running you should then switch to the regular +notation. +

DEPRECATION: the javadoc2 task simply points to the javadoc task and it's there for back compatibility reasons. Since this task will be removed in future versions, you are strongly encouraged to use javadoc @@ -1702,6 +1714,12 @@ Yes + maxmemory + Max amount of memory to allocate to the javadoc VM + all + No + + sourcefiles Space separated list of source files all @@ -1714,7 +1732,13 @@ all - Classpath + packageList + The name of a file containing the packages to process + all + No + + + classpath Specify where to find user class files all No @@ -1929,14 +1953,81 @@ doclet Specifies the class file that starts the doclet used in generating the documentation. + 1.2 No docletpath Specifies the path to the doclet class file that is specified with the -doclet option. + 1.2 + No + + + additionalparam + Lets you add additional parameters to the javadoc command line. Useful for doclets + 1.2 + No + + + +

Parameters specified as subelements

link

Parameters

Attribute	Description	Required
href	The URL for the external documentation you wish to link to	Yes
offline	True if this link is not available online at the time of + generating the documentation	No
packagelistLoc	The location to the directory containing the package-list file for + the external documentation	Only if the offline attribute is true

groups

Attribute	Description	Required
title	Title of the group	Yes
packages	List of packages to include in that group	Yes

Example

  <javadoc packagenames="com.dummy.test.*"
              sourcepath="src"
  @@ -1946,8 +2037,13 @@
              use="true"
              windowtitle="Test API"
              doctitle="<h1>Test</h1>"
  -           bottom="<i>Copyright &#169; 2000 Dummy Corp. All Rights Reserved.</i>"
  -  />

KeySubst

Description

. */ package org.apache.tools.ant; import java.util.*; import java.io.*; /** * A Path tokenizer takes a path and returns the components that make up * that path. * * The path can use path separators of either ':' or ';' and file separators * of either '/' or '\' * * @author Conor MacNeill (conor@ieee.org) * */ public class PathTokenizer { /** * A tokenizer to break the string up based on the ':' or ';' separators. */ StringTokenizer tokenizer; /** * A String which stores any path components which have been read ahead. */ String lookahead = null; public PathTokenizer(String path) { tokenizer = new StringTokenizer(path, ":;", false); } public boolean hasMoreTokens() { if (lookahead != null) { return true; } return tokenizer.hasMoreTokens(); } public String nextToken() throws NoSuchElementException { if (lookahead != null) { String token = lookahead; lookahead = null; return token; } else { String token = tokenizer.nextToken().trim(); if (token.length() == 1 && Character.isLetter(token.charAt(0)) && File.pathSeparator.equals(";") && tokenizer.hasMoreTokens()) { // we are on a dos style system so this path could be a drive // spec. We look at the next token String nextToken = tokenizer.nextToken().trim(); if (nextToken.startsWith("\\") || nextToken.startsWith("/")) { // we know we are on a DOS style platform and the next path starts with a // slash or backslash, so we know this is a drive spec token += ":" + nextToken; } else { // store the token just read for next time lookahead = nextToken; } } return token; } } } 1.9 +179 -16 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java Index: Javadoc.java =================================================================== RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- Javadoc.java 2000/06/14 12:42:14 1.8 +++ Javadoc.java 2000/06/29 15:32:39 1.9 @@ -75,11 +75,14 @@ * * @author Jon S. Stevens jon@clearink.com * @author Stefano Mazzocchi stefano@apache.org + * @author Patrick Chanezon chanezon@netscape.com */ public class Javadoc extends Exec { + private String maxmemory = null; private String sourcePath = null; + private String additionalParam = null; private File destDir = null; private File overviewFile = null; private String sourceFiles = null; @@ -106,8 +109,8 @@ private String header = null; private String footer = null; private String bottom = null; - private String link = null; private String linkoffline = null; + private String link = null; private String group = null; private boolean nodeprecated = false; private boolean nodeprecatedlist = false; @@ -119,7 +122,18 @@ private File helpfile = null; private String docencoding = null; private Vector compileList = new Vector(10); + private String packageList = null; + private Vector links = new Vector(2); + private Vector groups = new Vector(2); + + public void setMaxmemory(String src){ + maxmemory = src; + } + public void setadditionalParam(String src){ + additionalParam = src; + } + public void setSourcepath(String src) { sourcePath = project.translatePath(src); } @@ -201,15 +215,15 @@ public void setBottom(String src) { bottom = src; } - public void setLink(String src) { - link = src; - } public void setLinkoffline(String src) { linkoffline = src; } public void setGroup(String src) { group = src; } + public void setLink(String src) { + link = src; + } public void setNodeprecated(String src) { nodeprecated = Project.toBoolean(src); } @@ -234,7 +248,79 @@ public void setDocencoding(String src) { docencoding = src; } + public void setPackageList(String src) { + packageList = src; + } + + public LinkArgument createLink() { + LinkArgument la = new LinkArgument(); + links.addElement(la); + return la; + } + + public class LinkArgument { + private String href; + private boolean offline = false; + private String packagelistLoc; + + public LinkArgument() { + } + + public void setHref(String hr) { + href = hr; + } + + public String getHref() { + return href; + } + + public void setPackagelistLoc(String src) { + packagelistLoc = src; + } + + public String getPackagelistLoc() { + return packagelistLoc; + } + + public void setOffline(String offline) { + this.offline = Project.toBoolean(offline); + } + + public boolean isLinkOffline() { + return offline; + } + } + + public GroupArgument createGroup() { + GroupArgument ga = new GroupArgument(); + groups.addElement(ga); + return ga; + } + + public class GroupArgument { + private String title; + private String packages; + public GroupArgument() { + } + + public void setTitle(String src) { + title = src; + } + + public String getTitle() { + return title; + } + + public void setPackages(String src) { + packages = src; + } + + public String getPackages() { + return packages; + } + } + public void execute() throws BuildException { if (sourcePath == null && destDir == null ) { String msg = "sourcePath and destDir attributes must be set!"; @@ -251,6 +337,16 @@ if (classpath == null) classpath = System.getProperty("java.class.path"); + + if(maxmemory != null){ + if(javadoc1){ + argList.addElement("-J-mx" + maxmemory); + } + else{ + argList.addElement("-J-Xmx" + maxmemory); + } + } + if ( (!javadoc1) || (sourcePath == null) ) { argList.addElement("-classpath"); argList.addElement(classpath); @@ -358,15 +454,46 @@ argList.addElement("-bottom"); argList.addElement(bottom); } + + // add the single link arguments if (link != null) { argList.addElement("-link"); argList.addElement(link); } + + // add the links arguments + if (links.size() != 0) { + for (Enumeration e = links.elements(); e.hasMoreElements(); ) { + LinkArgument la = (LinkArgument)e.nextElement(); + + if (la.getHref() == null) { + throw new BuildException("Links must provide the RUL to the external class documentation."); + } + + if (la.isLinkOffline()) { + String packageListLocation = la.getPackagelistLoc(); + if (packageListLocation == null) { + throw new BuildException("The package list location for link " + la.getHref() + + " must be provided because the link is offline"); + } + argList.addElement("-linkoffline"); + argList.addElement(la.getHref()); + argList.addElement(packageListLocation); + } + else { + argList.addElement("-link"); + argList.addElement(la.getHref()); + } + } + } + + // add the single linkoffline arguments if (linkoffline != null) { argList.addElement("-linkoffline"); argList.addElement(linkoffline); } - + + // add the single group arguments // Javadoc 1.2 rules: // Multiple -group args allowed. // Each arg includes 3 strings: -group [name] [packagelist]. @@ -391,6 +518,27 @@ } } } + + // add the group arguments + if (groups.size() != 0) { + String title = null; + String packages = null; + GroupArgument ga = null; + for (int i = 0; i < groups.size(); i++) { + ga = (GroupArgument)groups.get(i); + if (ga != null) { + title = ga.getTitle(); + packages = ga.getPackages(); + } + if (title != null) { + argList.addElement("-group"); + argList.addElement(title); + if (packages != null) { + argList.addElement(packages); + } + } + } + } if (stylesheetfile != null) { argList.addElement("-stylesheetfile"); @@ -400,6 +548,9 @@ argList.addElement("-helpfile"); argList.addElement(helpfile.getAbsolutePath()); } + if (additionalParam != null) { + argList.addElement(additionalParam); + } } if ((packageNames != null) && (packageNames.length() > 0)) { @@ -425,6 +576,9 @@ } } + if (packageList != null) { + argList.addElement("@" + packageList); + } project.log("Javadoc args: " + argList.toString(), "javadoc", project.MSG_VERBOSE); project.log("Javadoc execution", project.MSG_INFO); @@ -453,20 +607,29 @@ * with the packages found in that path subdirs matching one of the given * patterns. */ - private void evaluatePackages(String source, Vector packages, Vector argList) { + private void evaluatePackages(String sourcePath, Vector packages, Vector argList) { project.log("Parsing source files for packages", project.MSG_INFO); - project.log("Source dir = " + source, project.MSG_VERBOSE); + project.log("Source path = " + sourcePath, project.MSG_VERBOSE); project.log("Packages = " + packages, project.MSG_VERBOSE); - Hashtable map = mapClasses(new File(source)); - - Enumeration e = map.keys(); - while (e.hasMoreElements()) { - String pack = (String) e.nextElement(); - for (int i = 0; i < packages.size(); i++) { - if (matches(pack, (String) packages.elementAt(i))) { - argList.addElement(pack); - break; + Vector addedPackages = new Vector(); + PathTokenizer tokenizer = new PathTokenizer(sourcePath); + while (tokenizer.hasMoreTokens()) { + File source = new File(project.translatePath(tokenizer.nextToken())); + + Hashtable map = mapClasses(source); + + Enumeration e = map.keys(); + while (e.hasMoreElements()) { + String pack = (String) e.nextElement(); + for (int i = 0; i < packages.size(); i++) { + if (matches(pack, (String) packages.elementAt(i))) { + if (!addedPackages.contains(pack)) { + argList.addElement(pack); + addedPackages.addElement(pack); + } + break; + } } } } 1.3 +0 -1 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/RenameExtensions.java Index: RenameExtensions.java =================================================================== RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/RenameExtensions.java,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- RenameExtensions.java 2000/03/20 15:45:34 1.2 +++ RenameExtensions.java 2000/06/29 15:32:43 1.3 @@ -73,7 +73,6 @@ /** * * @author dion - * @version */ public class RenameExtensions extends MatchingTask {