Return-Path: Delivered-To: apmail-jakarta-ant-dev-archive@apache.org Received: (qmail 84418 invoked from network); 18 Apr 2002 06:55:08 -0000 Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131) by daedalus.apache.org with SMTP; 18 Apr 2002 06:55:08 -0000 Received: (qmail 28013 invoked by uid 97); 18 Apr 2002 06:55:08 -0000 Delivered-To: qmlist-jakarta-archive-ant-dev@jakarta.apache.org Received: (qmail 27996 invoked by uid 97); 18 Apr 2002 06:55:08 -0000 Mailing-List: contact ant-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Ant Developers List" Reply-To: "Ant Developers List" Delivered-To: mailing list ant-dev@jakarta.apache.org Received: (qmail 27985 invoked by uid 97); 18 Apr 2002 06:55:07 -0000 Date: 18 Apr 2002 06:54:55 -0000 Message-ID: <20020418065455.91857.qmail@icarus.apache.org> From: conor@apache.org To: jakarta-ant-cvs@apache.org Subject: cvs commit: jakarta-ant/src/main/org/apache/tools/ant/taskdefs Definer.java ExecuteJava.java Java.java Javac.java Javadoc.java X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N conor 02/04/17 23:54:55 Modified: src/main/org/apache/tools/ant/taskdefs Definer.java ExecuteJava.java Java.java Javac.java Javadoc.java Log: Ongoing Javadocs Revision Changes Path 1.15 +5 -0 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Definer.java Index: Definer.java =================================================================== RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Definer.java,v retrieving revision 1.14 retrieving revision 1.15 diff -u -w -u -r1.14 -r1.15 --- Definer.java 12 Apr 2002 14:46:44 -0000 1.14 +++ Definer.java 18 Apr 2002 06:54:54 -0000 1.15 @@ -91,6 +91,11 @@ Project.MSG_WARN); } + /** + * Set the classpath to be used when searching for component being defined + * + * @param classpath an Ant Path object containing the classpath. + */ public void setClasspath(Path classpath) { if (this.classpath == null) { this.classpath = classpath; 1.26 +5 -0 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/ExecuteJava.java Index: ExecuteJava.java =================================================================== RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/ExecuteJava.java,v retrieving revision 1.25 retrieving revision 1.26 diff -u -w -u -r1.25 -r1.26 --- ExecuteJava.java 15 Apr 2002 15:33:08 -0000 1.25 +++ ExecuteJava.java 18 Apr 2002 06:54:54 -0000 1.26 @@ -90,6 +90,11 @@ this.javaCommand = javaCommand; } + /** + * Set the classpath to be used when running the Java class + * + * @param p an Ant Path object containing the classpath. + */ public void setClasspath(Path p) { classpath = p; } 1.44 +3 -1 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Java.java Index: Java.java =================================================================== RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Java.java,v retrieving revision 1.43 retrieving revision 1.44 diff -u -w -u -r1.43 -r1.44 --- Java.java 15 Apr 2002 15:33:09 -0000 1.43 +++ Java.java 18 Apr 2002 06:54:54 -0000 1.44 @@ -184,7 +184,9 @@ } /** - * Set the classpath to be used for this compilation. + * Set the classpath to be used when running the Java class + * + * @param s an Ant Path object containing the classpath. */ public void setClasspath(Path s) { createClasspath().append(s); 1.101 +3 -1 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Javac.java Index: Javac.java =================================================================== RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Javac.java,v retrieving revision 1.100 retrieving revision 1.101 diff -u -w -u -r1.100 -r1.101 --- Javac.java 16 Apr 2002 10:36:25 -0000 1.100 +++ Javac.java 18 Apr 2002 06:54:54 -0000 1.101 @@ -102,7 +102,7 @@ * @author Stefan Bodewig * @author J D Glanville * - * @version $Revision: 1.100 $ + * @version $Revision: 1.101 $ * * @since Ant 1.1 * @@ -277,6 +277,8 @@ /** * Set the classpath to be used for this compilation. + * + * @param classpath an Ant Path object containing the compilation classpath. */ public void setClasspath(Path classpath) { if (compileClasspath == null) { 1.93 +502 -36 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.92 retrieving revision 1.93 diff -u -w -u -r1.92 -r1.93 --- Javadoc.java 16 Apr 2002 10:36:25 -0000 1.92 +++ Javadoc.java 18 Apr 2002 06:54:54 -0000 1.93 @@ -109,39 +109,92 @@ * @ant.task category="java" */ public class Javadoc extends Task { - + /** + * Inner class used to manage doclet parameters. + */ public class DocletParam { + /** The parameter name */ private String name; + + /** The parameter value */ private String value; + /** + * Set the name of the parameter. + * + * @param name the name of the doclet parameter + */ public void setName(String name) { this.name = name; } + /** + * Get the parameter name. + * + * @return the parameter's name. + */ public String getName() { return name; } + /** + * Set the parameter value. + * + * Note that only string values are supported. No resolution of file + * paths is performed. + * + * @param value the parameter value. + */ public void setValue(String value) { this.value = value; } + /** + * Get the parameter value. + * + * @return the parameter value. + */ public String getValue() { return value; } } + /** + * A project aware class used for Javadoc extensions which take a name + * and a path such as doclet and taglet arguments. + * + * @author Conor MacNeill + */ public static class ExtensionInfo extends ProjectComponent { + /** The name of the extension */ private String name; + + /** The optional path to use to load the extension */ private Path path; + + /** + * Set the name of the extension + * + * @param name the extension's name. + */ public void setName(String name) { this.name = name; } + /** + * Get the name of the extension. + * + * @return the extension's name. + */ public String getName() { return name; } + /** + * Set the path to use when loading the component. + * + * @param path a Path instance containing the classpath to use. + */ public void setPath(Path path) { if (this.path == null) { this.path = path; @@ -150,10 +203,22 @@ } } + /** + * Get the extension's path. + * + * @return the path to be used to load the extension. + * May be null + */ public Path getPath() { return path; } + /** + * Create an empty nested path to be configured by Ant with the + * classpath for the extension. + * + * @return a new Path instance to be configured. + */ public Path createPath() { if (path == null) { path = new Path(getProject()); @@ -163,16 +228,29 @@ /** * Adds a reference to a CLASSPATH defined elsewhere. + * + * @param r the reference containing the path. */ public void setPathRef(Reference r) { createPath().setRefid(r); } } + /** + * This class stores info about doclets. + * + * @author Conor MacNeill + */ public class DocletInfo extends ExtensionInfo { + /** Collection of doclet parameters. */ private Vector params = new Vector(); + /** + * Create a doclet parameter to be configured by Ant. + * + * @return a new DocletParam instance to be configured. + */ public DocletParam createParam() { DocletParam param = new DocletParam(); params.addElement(param); @@ -180,45 +258,112 @@ return param; } + /** + * Get the doclet's parameters. + * + * @return an Enumeration of DocletParam instances. + */ public Enumeration getParams() { return params.elements(); } } + /** + * Used to track info about the packages to be javadoc'd + */ public static class PackageName { + /** The package name */ private String name; + + /** + * Set the name of the package + * + * @param name the package name. + */ public void setName(String name) { this.name = name; } + + /** + * Get the package name. + * + * @return the package's name. + */ public String getName() { return name; } + + /** + * @see java.lang.Object#toString + */ public String toString() { return getName(); } } + /** + * This class is used to manage the source files to be processed. + */ public static class SourceFile { + /** The source file */ private File file; + + /** + * Set the source file. + * + * @param file the source file. + */ public void setFile(File file) { this.file = file; } + + /** + * Get the source file. + * + * @return the source file. + */ public File getFile() { return file; } } + /** + * An HTML element in the javadoc. + * + * This class is used for those javadoc elements which contain HTML such as + * footers, headers, etc. + */ public static class Html { + /** The text for the element */ private StringBuffer text = new StringBuffer(); + + /** + * Add text to the element. + * + * @param t the text to be added. + */ public void addText(String t) { text.append(t); } + + /** + * Get the current text for the element. + * + * @return the current text. + */ public String getText() { return text.toString(); } } + /** + * EnumeratedAttribute implementation supporting the javadoc scoping + * values. + */ public static class AccessType extends EnumeratedAttribute { + /** + * @see EnumeratedAttributes#getValues(). + */ public String[] getValues() { // Protected first so if any GUI tool offers a default // based on enum #0, it will be right. @@ -226,21 +371,38 @@ } } + /** The command line built to execute Javadoc. */ private Commandline cmd = new Commandline(); + + /** Flag which indicates if javadoc from JDK 1.1 is to be used. */ private static boolean javadoc1 = (JavaEnvUtils.getJavaVersion() == JavaEnvUtils.JAVA_1_1); + /** Flag which indicates if javadoc from JDK 1.4 is available */ private static boolean javadoc4 = (JavaEnvUtils.getJavaVersion() != JavaEnvUtils.JAVA_1_1 && JavaEnvUtils.getJavaVersion() != JavaEnvUtils.JAVA_1_2 && JavaEnvUtils.getJavaVersion() != JavaEnvUtils.JAVA_1_3); + /** + * Utility method to add an argument to the command line conditionally + * based on the given flag. + * + * @param b the flag which controls if the argument is added. + * @param arg the argument value. + */ private void addArgIf(boolean b, String arg) { if (b) { cmd.createArgument().setValue(arg); } } + /** + * Utility method to add a non JDK1.1 javadoc argument. + * + * @param key the argument name. + * @param value the argument value. + */ private void add12ArgIfNotEmpty(String key, String value) { if (!javadoc1) { if (value != null && value.length() != 0) { @@ -253,12 +415,22 @@ } } + /** + * Utility method to add a non-JDK1.1 argument to the command line + * conditionally based on the given flag. + * + * @param b the flag which controls if the argument is added. + * @param arg the argument value. + */ private void add12ArgIf(boolean b, String arg) { if (!javadoc1 && b) { cmd.createArgument().setValue(arg); } } + /** + * Flag which indicates if the task should fail if there is a javadoc error. + */ private boolean failOnError = false; private Path sourcePath = null; private File destDir = null; @@ -288,6 +460,8 @@ /** * Work around command line length limit by using an external file * for the sourcefiles. + * + * @param b true if an external file is to be used. */ public void setUseExternalFile(boolean b) { if (!javadoc1) { @@ -306,6 +480,12 @@ this.useDefaultExcludes = useDefaultExcludes; } + /** + * Set the maximum memory to be used by the javadoc process + * + * @param max a string indicating the maximum memory according to the + * JVM conventions (e.g. 128m is 128 Megabytes) + */ public void setMaxmemory(String max){ if (javadoc1) { cmd.createArgument().setValue("-J-mx" + max); @@ -314,10 +494,20 @@ } } + /** + * Set an additional parameter on the command line + * + * @param add the additional command line parameter for the javadoc task. + */ public void setAdditionalparam(String add){ cmd.createArgument().setLine(add); } + /** + * Specify where to find source file + * + * @param src a Path instance containing the various source directories. + */ public void setSourcepath(Path src) { if (sourcePath == null) { sourcePath = src; @@ -325,6 +515,13 @@ sourcePath.append(src); } } + + /** + * Create a path to be configured with the locations of the source + * files. + * + * @return a new Path instance to be configured by the Ant core. + */ public Path createSourcepath() { if (sourcePath == null) { sourcePath = new Path(project); @@ -334,16 +531,29 @@ /** * Adds a reference to a CLASSPATH defined elsewhere. + * + * @param r the reference containing the source path definition. */ public void setSourcepathRef(Reference r) { createSourcepath().setRefid(r); } + /** + * Set the directory where the Javadoc output will be generated. + * + * @param dir the destination directory. + */ public void setDestdir(File dir) { destDir = dir; cmd.createArgument().setValue("-d"); cmd.createArgument().setFile(destDir); } + + /** + * Set the list of source files to process. + * + * @param src a comma separated list of source files. + */ public void setSourcefiles(String src) { StringTokenizer tok = new StringTokenizer(src, ","); while (tok.hasMoreTokens()) { @@ -353,11 +563,26 @@ addSource(sf); } } + + /** + * Add a single source file. + * + * @param sf the source file to be processed. + */ public void addSource(SourceFile sf) { sourceFiles.addElement(sf); } - public void setPackagenames(String src) { - StringTokenizer tok = new StringTokenizer(src, ","); + + /** + * Set the package names to be processed. + * + * @param packages a comma separated list of packages specs + * (may be wildcarded). + * + * @see #addPackage for wildcard information. + */ + public void setPackagenames(String packages) { + StringTokenizer tok = new StringTokenizer(packages, ","); while (tok.hasMoreTokens()) { String p = tok.nextToken(); PackageName pn = new PackageName(); @@ -365,12 +590,27 @@ addPackage(pn); } } + + /** + * Add a single package to be processed. + * + * If the package name ends with ".*" the Javadoc task + * will find and process all subpackages. + * + * @param pn the package name, possibly wildcarded. + */ public void addPackage(PackageName pn) { packageNames.addElement(pn); } - public void setExcludePackageNames(String src) { - StringTokenizer tok = new StringTokenizer(src, ","); + /** + * Set the list of packages to be excluded. + * + * @param packages a comma separated list of packages to be excluded. + * This may not include wildcards. + */ + public void setExcludePackageNames(String packages) { + StringTokenizer tok = new StringTokenizer(packages, ","); while (tok.hasMoreTokens()) { String p = tok.nextToken(); PackageName pn = new PackageName(); @@ -378,45 +618,111 @@ addExcludePackage(pn); } } + + /** + * Add a package to be excluded from the javadoc run. + * + * @param pn the name of the package (wildcards are not permitted). + */ public void addExcludePackage(PackageName pn) { excludePackageNames.addElement(pn); } + /** + * Specify the fiel containing the overview to be included in the generated + * documentation. + * + * @param f the file containing the overview. + */ public void setOverview(File f) { if (!javadoc1) { cmd.createArgument().setValue("-overview"); cmd.createArgument().setFile(f); } } + + /** + * Indicate whether only public classes and members are to be included in + * the scope processed + * + * @param b true if scope is to be public. + */ public void setPublic(boolean b) { addArgIf(b, "-public"); } + + /** + * Indicate whether only protected and public classes and members are to + * be included in the scope processed + * + * @param b true if scope is to be protected. + */ public void setProtected(boolean b) { addArgIf(b, "-protected"); } + + /** + * Indicate whether only package, protected and public classes and + * members are to be included in the scope processed + * + * @param b true if scope is to be package level. + */ public void setPackage(boolean b) { addArgIf(b, "-package"); } + + /** + * Indicate whether all classes and + * members are to be included in the scope processed + * + * @param b true if scope is to be private level. + */ public void setPrivate(boolean b) { addArgIf(b, "-private"); } + + /** + * Set the scope to be processed. This is an alternative to the + * use of the setPublic, setPrivate, etc methods. It gives better build + * file control over what scope is processed. + * + * @param at the scope to be processed. + */ public void setAccess(AccessType at) { cmd.createArgument().setValue("-" + at.getValue()); } - public void setDoclet(String src) { + + /** + * Set the class that starts the doclet used in generating the + * documentation. + * + * @param docletName the name of the doclet class. + */ + public void setDoclet(String docletName) { if (doclet == null) { doclet = new DocletInfo(); } - doclet.setName(src); + doclet.setName(docletName); } - public void setDocletPath(Path src) { + /** + * Set the classpath used to find the doclet class. + * + * @param docletPath the doclet classpath. + */ + public void setDocletPath(Path docletPath) { if (doclet == null) { doclet = new DocletInfo(); } - doclet.setPath(src); + doclet.setPath(docletPath); } + /** + * Set the classpath used to find the doclet class by reference. + * + * @param r the reference to the Path instance to use as the doclet + * classpath. + */ public void setDocletPathRef(Reference r) { if (doclet == null) { doclet = new DocletInfo(); @@ -424,15 +730,33 @@ doclet.createPath().setRefid(r); } + /** + * Create a doclet to be used in the documentation generation. + * + * @return a new DocletInfo instance to be configured. + */ public DocletInfo createDoclet() { doclet = new DocletInfo(); return doclet; } + /** + * Add a taglet + * + * @param tagletInfo information about the taglet. + */ public void addTaglet(ExtensionInfo tagletInfo) { tags.addElement(tagletInfo); } + /** + * Indicate whether Javadoc should produce old style (JDK 1.1) + * documentation. + * + * This is not supported by JDK 1.1 and has been phased out in JDK 1.4 + * + * @param b if true attempt to generate old style documentation. + */ public void setOld(boolean b) { if (b) { if (javadoc1) { @@ -446,13 +770,26 @@ } } } - public void setClasspath(Path src) { + + /** + * Set the classpath to be used for this javadoc run. + * + * @param path an Ant Path object containing the compilation + * classpath. + */ + public void setClasspath(Path path) { if (classpath == null) { - classpath = src; + classpath = path; } else { - classpath.append(src); + classpath.append(path); } } + + /** + * Create a Path to be configured with the classpath to use + * + * @return a new Path instance to be configured with the classpath. + */ public Path createClasspath() { if (classpath == null) { classpath = new Path(project); @@ -462,18 +799,31 @@ /** * Adds a reference to a CLASSPATH defined elsewhere. + * + * @param r the reference to an instance defining the classpath. */ public void setClasspathRef(Reference r) { createClasspath().setRefid(r); } - public void setBootclasspath(Path src) { + /** + * Set the boot classpath to use. + * + * @param path the boot classpath. + */ + public void setBootclasspath(Path path) { if (bootclasspath == null) { - bootclasspath = src; + bootclasspath = path; } else { - bootclasspath.append(src); + bootclasspath.append(path); } } + + /** + * Create a Path to be configured with the boot classpath + * + * @return a new Path instance to be configured with the boot classpath. + */ public Path createBootclasspath() { if (bootclasspath == null) { bootclasspath = new Path(project); @@ -483,84 +833,200 @@ /** * Adds a reference to a CLASSPATH defined elsewhere. + * + * @param r the reference to an instance defining the bootclasspath. */ public void setBootClasspathRef(Reference r) { createBootclasspath().setRefid(r); } - public void setExtdirs(String src) { + /** + * Set the location of the extensions directories. + * + * @param path the string version of the path. + * @deprecated Use the {@link #setExtdirs(Path)} version. + */ + public void setExtdirs(String path) { + if (!javadoc1) { + cmd.createArgument().setValue("-extdirs"); + cmd.createArgument().setValue(path); + } + } + + /** + * Set the location of the extensions directories. + * + * @param path a path containing the extension directories. + */ + public void setExtdirs(Path path) { if (!javadoc1) { cmd.createArgument().setValue("-extdirs"); - cmd.createArgument().setValue(src); + cmd.createArgument().setPath(path); } } + + /** + * Run javadoc in verbose mode + * + * @param b true if operation is to be verbose. + */ public void setVerbose(boolean b) { add12ArgIf(b, "-verbose"); } - public void setLocale(String src) { + + /** + * Set the local to use in documentation generation. + * + * @param locale the locale to use. + */ + public void setLocale(String locale) { if (!javadoc1) { // createArgument(true) is necessary to make sure, -locale // is the first argument (required in 1.3+). - cmd.createArgument(true).setValue(src); + cmd.createArgument(true).setValue(locale); cmd.createArgument(true).setValue("-locale"); } } + + /** + * Set the encoding name of the source files, + * + * @param enc the name of the encoding for the source files. + */ public void setEncoding(String enc) { cmd.createArgument().setValue("-encoding"); cmd.createArgument().setValue(enc); } - public void setVersion(boolean src) { - version = src; + + /** + * Include the version tag in the generated documentation. + * + * @param b true if the version tag should be included. + */ + public void setVersion(boolean b) { + this.version = b; } + + /** + * Generate the "use" page for each package. + * + * @param b true if the use page should be generated. + */ public void setUse(boolean b) { add12ArgIf(b, "-use"); } - public void setAuthor(boolean src) { - author = src; + + + /** + * Include the author tag in the generated documentation. + * + * @param b true if the author tag should be included. + */ + public void setAuthor(boolean b) { + author = b; } + + /** + * Generate a split index + * + * @param b true if the index should be split into a file per letter. + */ public void setSplitindex(boolean b) { add12ArgIf(b, "-splitindex"); } - public void setWindowtitle(String src) { - add12ArgIfNotEmpty("-windowtitle", src); + + /** + * Set the title to be placed in the HTML <title> tag of the + * generated documentation. + * + * @param title the window title to use. + */ + public void setWindowtitle(String title) { + add12ArgIfNotEmpty("-windowtitle", title); } - public void setDoctitle(String src) { + + /** + * Set the title of the generated overview page. + * + * @param doctitle the Document title. + */ + public void setDoctitle(String doctitle) { Html h = new Html(); - h.addText(src); + h.addText(doctitle); addDoctitle(h); } + + /** + * Add a document title to use for the overview page. + * + * @param text the HTML element containing the document title. + */ public void addDoctitle(Html text) { if (!javadoc1) { doctitle = text; } } - public void setHeader(String src) { + + /** + * Set the header text to be placed at the top of each output file. + * + * @param header the header text + */ + public void setHeader(String header) { Html h = new Html(); - h.addText(src); + h.addText(header); addHeader(h); } + + /** + * Set the header text to be placed at the top of each output file. + * + * @param text the header text + */ public void addHeader(Html text) { if (!javadoc1) { header = text; } } - public void setFooter(String src) { + /** + * Set the footer text to be placed at the bottom of each output file. + * + * @param footer the footer text. + */ + public void setFooter(String footer) { Html h = new Html(); - h.addText(src); + h.addText(footer); addFooter(h); } + + /** + * Set the footer text to be placed at the bottom of each output file. + * + * @param text the footer text. + */ public void addFooter(Html text) { if (!javadoc1) { footer = text; } } - public void setBottom(String src) { + /** + * Set the text to be placed at the bottom of each output file. + * + * @param bottom the bottom text. + */ + public void setBottom(String bottom) { Html h = new Html(); - h.addText(src); + h.addText(bottom); addBottom(h); } + + /** + * Set the text to be placed at the bottom of each output file. + * + * @param text the bottom text. + */ public void addBottom(Html text) { if (!javadoc1) { bottom = text; @@ -572,7 +1038,7 @@ LinkArgument le = createLink(); le.setOffline(true); String linkOfflineError = "The linkoffline attribute must include" - + " an URL and a package-list file location separated by a" + + " a URL and a package-list file location separated by a" + " space"; if (src.trim().length() == 0) { throw new BuildException(linkOfflineError); -- To unsubscribe, e-mail: For additional commands, e-mail: