From ce84792f2d526fa1e772585f4b5fdfbb35ca8684 Mon Sep 17 00:00:00 2001 From: Matthew Jason Benson Date: Mon, 7 Feb 2005 23:18:03 +0000 Subject: [PATCH] Javadoc git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@277612 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/tools/ant/DirectoryScanner.java | 151 ++++++++-------- .../apache/tools/ant/types/Commandline.java | 164 +++++++++--------- 2 files changed, 159 insertions(+), 156 deletions(-) diff --git a/src/main/org/apache/tools/ant/DirectoryScanner.java b/src/main/org/apache/tools/ant/DirectoryScanner.java index 81e40e73f..d2a294a90 100644 --- a/src/main/org/apache/tools/ant/DirectoryScanner.java +++ b/src/main/org/apache/tools/ant/DirectoryScanner.java @@ -190,8 +190,9 @@ public class DirectoryScanner /** Selectors that will filter which files are in our candidate list. */ protected FileSelector[] selectors = null; - /** The files which matched at least one include and no excludes - * and were selected. + /** + * The files which matched at least one include and no excludes + * and were selected. */ protected Vector filesIncluded; @@ -204,8 +205,9 @@ public class DirectoryScanner */ protected Vector filesExcluded; - /** The directories which matched at least one include and no excludes - * and were selected. + /** + * The directories which matched at least one include and no excludes + * and were selected. */ protected Vector dirsIncluded; @@ -218,13 +220,15 @@ public class DirectoryScanner */ protected Vector dirsExcluded; - /** The files which matched at least one include and no excludes and - * which a selector discarded. + /** + * The files which matched at least one include and no excludes and + * which a selector discarded. */ protected Vector filesDeselected; - /** The directories which matched at least one include and no excludes - * but which a selector discarded. + /** + * The directories which matched at least one include and no excludes + * but which a selector discarded. */ protected Vector dirsDeselected; @@ -346,6 +350,7 @@ public class DirectoryScanner protected static boolean matchPatternStart(String pattern, String str) { return SelectorUtils.matchPatternStart(pattern, str); } + /** * Tests whether or not a given path matches the start of a given * pattern up to the first "**". @@ -462,9 +467,8 @@ public class DirectoryScanner * default exclude. * * @param s A string to add as an exclude pattern. - * @return true if the string was added - * false if it already - * existed. + * @return true if the string was added; + * false if it already existed. * * @since Ant 1.6 */ @@ -481,9 +485,9 @@ public class DirectoryScanner * * @param s The string to attempt to remove. * @return true if s was a default - * exclude (and thus was removed), + * exclude (and thus was removed); * false if s was not - * in the default excludes list to begin with + * in the default excludes list to begin with. * * @since Ant 1.6 */ @@ -492,13 +496,12 @@ public class DirectoryScanner } /** - * Go back to the hard wired default exclude patterns + * Go back to the hardwired default exclude patterns. * * @since Ant 1.6 */ public static void resetDefaultExcludes() { defaultExcludes = new Vector(); - for (int i = 0; i < DEFAULTEXCLUDES.length; i++) { defaultExcludes.add(DEFAULTEXCLUDES[i]); } @@ -530,7 +533,7 @@ public class DirectoryScanner } /** - * Returns the base directory to be scanned. + * Return the base directory to be scanned. * This is the directory which is scanned recursively. * * @return the base directory to be scanned @@ -541,46 +544,46 @@ public class DirectoryScanner /** * Find out whether include exclude patterns are matched in a - * case sensitive way - * @return whether or not the scanning is case sensitive - * @since ant 1.6 + * case sensitive way. + * @return whether or not the scanning is case sensitive. + * @since Ant 1.6 */ public boolean isCaseSensitive() { return isCaseSensitive; } /** - * Sets whether or not include and exclude patterns are matched - * in a case sensitive way + * Set whether or not include and exclude patterns are matched + * in a case sensitive way. * * @param isCaseSensitive whether or not the file system should be - * regarded as a case sensitive one + * regarded as a case sensitive one. */ public void setCaseSensitive(boolean isCaseSensitive) { this.isCaseSensitive = isCaseSensitive; } /** - * gets whether or not a DirectoryScanner follows symbolic links + * Get whether or not a DirectoryScanner follows symbolic links. * - * @return flag indicating whether symbolic links should be followed + * @return flag indicating whether symbolic links should be followed. * - * @since ant 1.6 + * @since Ant 1.6 */ public boolean isFollowSymlinks() { return followSymlinks; } /** - * Sets whether or not symbolic links should be followed. + * Set whether or not symbolic links should be followed. * - * @param followSymlinks whether or not symbolic links should be followed + * @param followSymlinks whether or not symbolic links should be followed. */ public void setFollowSymlinks(boolean followSymlinks) { this.followSymlinks = followSymlinks; } /** - * Sets the list of include patterns to use. All '/' and '\' characters + * Set the list of include patterns to use. All '/' and '\' characters * are replaced by File.separatorChar, so the separator used * need not match File.separatorChar. *

@@ -590,7 +593,7 @@ public class DirectoryScanner * May be null, indicating that all files * should be included. If a non-null * list is given, all elements must be - * non-null. + * non-null. */ public void setIncludes(String[] includes) { if (includes == null) { @@ -603,9 +606,8 @@ public class DirectoryScanner } } - /** - * Sets the list of exclude patterns to use. All '/' and '\' characters + * Set the list of exclude patterns to use. All '/' and '\' characters * are replaced by File.separatorChar, so the separator used * need not match File.separatorChar. *

@@ -628,10 +630,9 @@ public class DirectoryScanner } /** - * Adds to the list of exclude patterns to use. All '/' and '\' + * Add to the list of exclude patterns to use. All '/' and '\' * characters are replaced by File.separatorChar, so - * the separator used need not match - * File.separatorChar. + * the separator used need not match File.separatorChar. *

* When a pattern ends with a '/' or '\', "**" is appended. * @@ -678,17 +679,16 @@ public class DirectoryScanner } /** - * Sets the selectors that will select the filelist. + * Set the selectors that will select the filelist. * - * @param selectors specifies the selectors to be invoked on a scan + * @param selectors specifies the selectors to be invoked on a scan. */ public void setSelectors(FileSelector[] selectors) { this.selectors = selectors; } - /** - * Returns whether or not the scanner has included all the files or + * Return whether or not the scanner has included all the files or * directories it has come across so far. * * @return true if all files and directories which have @@ -699,7 +699,7 @@ public class DirectoryScanner } /** - * Scans the base directory for files which match at least one include + * Scan the base directory for files which match at least one include * pattern and don't match any exclude patterns. If there are selectors * then the files must pass muster there, as well. * @@ -756,9 +756,9 @@ public class DirectoryScanner } /** - * this routine is actually checking all the include patterns in - * order to avoid scanning everything under base dir - * @since ant1.6 + * This routine is actually checking all the include patterns in + * order to avoid scanning everything under base dir. + * @since Ant 1.6 */ private void checkIncludePatterns() { Hashtable newroots = new Hashtable(); @@ -994,6 +994,7 @@ public class DirectoryScanner } } } + /** * Process included file. * @param name path of the file relative to the directory of the FileSet. @@ -1053,8 +1054,9 @@ public class DirectoryScanner } } } + /** - * Tests whether or not a name matches against at least one include + * Test whether or not a name matches against at least one include * pattern. * * @param name The name to match. Must not be null. @@ -1080,7 +1082,7 @@ public class DirectoryScanner } /** - * Tests whether or not a name matches the start of at least one include + * Test whether or not a name matches the start of at least one include * pattern. * * @param name The name to match. Must not be null. @@ -1099,20 +1101,20 @@ public class DirectoryScanner } /** - * find out whether one particular include pattern is more powerful - * than all the excludes - * note : the power comparison is based on the length of the include pattern - * and of the exclude patterns without the wildcards - * ideally the comparison should be done based on the depth - * of the match, that is to say how many file separators have been matched - * before the first ** or the end of the pattern + * Find out whether one particular include pattern is more powerful + * than all the excludes. + * Note: the power comparison is based on the length of the include pattern + * and of the exclude patterns without the wildcards. + * Ideally the comparison should be done based on the depth + * of the match; that is to say how many file separators have been matched + * before the first ** or the end of the pattern. * - * IMPORTANT : this function should return false "with care" + * IMPORTANT : this function should return false "with care". * - * @param name the relative path that one want to test - * @param includepattern one include pattern - * @return true if there is no exclude pattern more powerful than this include pattern - * @since ant1.6 + * @param name the relative path to test. + * @param includepattern one include pattern. + * @return true if there is no exclude pattern more powerful than this include pattern. + * @since Ant 1.6 */ private boolean isMorePowerfulThanExcludes(String name, String includepattern) { String soughtexclude = name + File.separator + "**"; @@ -1123,8 +1125,9 @@ public class DirectoryScanner } return true; } + /** - * Tests whether or not a name matches against at least one exclude + * Test whether or not a name matches against at least one exclude * pattern. * * @param name The name to match. Must not be null. @@ -1150,10 +1153,10 @@ public class DirectoryScanner } /** - * Tests whether a name should be selected. + * Test whether a file should be selected. * - * @param name the filename to check for selecting - * @param file the java.io.File object for this filename + * @param name the filename to check for selecting. + * @param file the java.io.File object for this filename. * @return false when the selectors says that the file * should not be selected, true otherwise. */ @@ -1169,7 +1172,7 @@ public class DirectoryScanner } /** - * Returns the names of the files which matched at least one of the + * Return the names of the files which matched at least one of the * include patterns and none of the exclude patterns. * The names are relative to the base directory. * @@ -1188,7 +1191,7 @@ public class DirectoryScanner /** * Return the count of included files. - * @return int. + * @return int. * @since Ant 1.6.3 */ public int getIncludedFilesCount() { @@ -1199,7 +1202,7 @@ public class DirectoryScanner } /** - * Returns the names of the files which matched none of the include + * Return the names of the files which matched none of the include * patterns. The names are relative to the base directory. This involves * performing a slow scan if one has not already been completed. * @@ -1216,7 +1219,7 @@ public class DirectoryScanner } /** - * Returns the names of the files which matched at least one of the + * Return the names of the files which matched at least one of the * include patterns and at least one of the exclude patterns. * The names are relative to the base directory. This involves * performing a slow scan if one has not already been completed. @@ -1234,7 +1237,7 @@ public class DirectoryScanner } /** - *

Returns the names of the files which were selected out and + *

Return the names of the files which were selected out and * therefore not ultimately included.

* *

The names are relative to the base directory. This involves @@ -1252,7 +1255,7 @@ public class DirectoryScanner } /** - * Returns the names of the directories which matched at least one of the + * Return the names of the directories which matched at least one of the * include patterns and none of the exclude patterns. * The names are relative to the base directory. * @@ -1271,7 +1274,7 @@ public class DirectoryScanner /** * Return the count of included directories. - * @return int. + * @return int. * @since Ant 1.6.3 */ public int getIncludedDirsCount() { @@ -1282,7 +1285,7 @@ public class DirectoryScanner } /** - * Returns the names of the directories which matched none of the include + * Return the names of the directories which matched none of the include * patterns. The names are relative to the base directory. This involves * performing a slow scan if one has not already been completed. * @@ -1299,7 +1302,7 @@ public class DirectoryScanner } /** - * Returns the names of the directories which matched at least one of the + * Return the names of the directories which matched at least one of the * include patterns and at least one of the exclude patterns. * The names are relative to the base directory. This involves * performing a slow scan if one has not already been completed. @@ -1317,7 +1320,7 @@ public class DirectoryScanner } /** - *

Returns the names of the directories which were selected out and + *

Return the names of the directories which were selected out and * therefore not ultimately included.

* *

The names are relative to the base directory. This involves @@ -1335,7 +1338,7 @@ public class DirectoryScanner } /** - * Adds default exclusions to the current exclusions set. + * Add default exclusions to the current exclusions set. */ public void addDefaultExcludes() { int excludesLength = excludes == null ? 0 : excludes.length; @@ -1354,7 +1357,7 @@ public class DirectoryScanner } /** - * Get the named resource + * Get the named resource. * @param name path name of the file relative to the dir attribute. * * @return the resource with the given name. @@ -1367,7 +1370,7 @@ public class DirectoryScanner } /** - * Returns a cached result of list performed on file, if + * Return a cached result of list performed on file, if * available. Invokes the method and caches the result otherwise. * * @since Ant 1.6 @@ -1558,7 +1561,7 @@ public class DirectoryScanner } /** - * Adds all patterns that are not real patterns (do not contain + * Add all patterns that are not real patterns (do not contain * wildcards) to the set and returns the real patterns. * * @since Ant 1.7 diff --git a/src/main/org/apache/tools/ant/types/Commandline.java b/src/main/org/apache/tools/ant/types/Commandline.java index e8f7ccbbd..f8167502a 100644 --- a/src/main/org/apache/tools/ant/types/Commandline.java +++ b/src/main/org/apache/tools/ant/types/Commandline.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2004 The Apache Software Foundation + * Copyright 2000-2005 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. @@ -30,7 +30,6 @@ import org.apache.tools.ant.BuildException; import org.apache.tools.ant.ProjectComponent; import org.apache.tools.ant.util.StringUtils; - /** * Commandline objects help handling command lines specifying processes to * execute. @@ -71,9 +70,9 @@ public class Commandline implements Cloneable { + StringUtils.LINE_SEP; /** - * create a command line from a string + * Create a command line from a string. * @param toProcess the line: the first element becomes the executable, the rest - * the arguments + * the arguments. */ public Commandline(String toProcess) { super(); @@ -87,7 +86,7 @@ public class Commandline implements Cloneable { } /** - * Create an empty command line + * Create an empty command line. */ public Commandline() { super(); @@ -101,7 +100,7 @@ public class Commandline implements Cloneable { private String[] parts; /** - * Sets a single commandline argument. + * Set a single commandline argument. * * @param value a single commandline argument. */ @@ -110,9 +109,9 @@ public class Commandline implements Cloneable { } /** - * Line to split into several commandline arguments. + * Set the line to split into several commandline arguments. * - * @param line line to split into several commandline arguments + * @param line line to split into several commandline arguments. */ public void setLine(String line) { if (line == null) { @@ -122,8 +121,8 @@ public class Commandline implements Cloneable { } /** - * Sets a single commandline argument and treats it like a - * PATH - ensures the right separator for the local platform + * Set a single commandline argument and treats it like a + * PATH--ensuring the right separator for the local platform * is used. * * @param value a single commandline argument. @@ -133,8 +132,8 @@ public class Commandline implements Cloneable { } /** - * Sets a single commandline argument from a reference to a - * path - ensures the right separator for the local platform + * Set a single commandline argument from a reference to a + * path--ensuring the right separator for the local platform * is used. * * @param value a single commandline argument. @@ -146,7 +145,7 @@ public class Commandline implements Cloneable { } /** - * Sets a single commandline argument to the absolute filename + * Set a single commandline argument to the absolute filename * of the given file. * * @param value a single commandline argument. @@ -156,7 +155,8 @@ public class Commandline implements Cloneable { } /** - * Returns the parts this Argument consists of. + * Return the constituent parts of this Argument. + * @return String[]. */ public String[] getParts() { return parts; @@ -174,15 +174,20 @@ public class Commandline implements Cloneable { private int position; private int realPos = -1; + /** + * Construct a marker for the specified position. + * @param position the position to mark. + */ Marker(int position) { this.position = position; } /** - * Return the number of arguments that preceeded this marker. + * Return the number of arguments that preceded this marker. * - *

The name of the executable - if set - is counted as the - * very first argument.

+ *

The name of the executable--if set--is counted as the + * first argument.

+ * @return int. */ public int getPosition() { if (realPos == -1) { @@ -197,7 +202,7 @@ public class Commandline implements Cloneable { } /** - * Creates an argument object. + * Create an argument object. * *

Each commandline object has at most one instance of the * argument class. This method calls @@ -211,7 +216,7 @@ public class Commandline implements Cloneable { } /** - * Creates an argument object and adds it to our list of args. + * Create an argument object and add it to our list of args. * *

Each commandline object has at most one instance of the * argument class.

@@ -230,8 +235,9 @@ public class Commandline implements Cloneable { } /** - * Sets the executable to run. All file separators in the string - * are converted to the platform specific value + * Set the executable to run. All file separators in the string + * are converted to the platform specific value. + * @param executable the String executable name. */ public void setExecutable(String executable) { if (executable == null || executable.length() == 0) { @@ -241,19 +247,17 @@ public class Commandline implements Cloneable { .replace('\\', File.separatorChar); } - /** - * get the executable - * @return the program to run -null if not yet set + * Get the executable. + * @return the program to run--null if not yet set. */ public String getExecutable() { return executable; } - /** - * append the arguments to the existing command - * @param line an array of arguments to append + * Append the arguments to the existing command. + * @param line an array of arguments to append. */ public void addArguments(String[] line) { for (int i = 0; i < line.length; i++) { @@ -262,7 +266,8 @@ public class Commandline implements Cloneable { } /** - * Returns the executable and all defined arguments. + * Return the executable and all defined arguments. + * @return String[]. */ public String[] getCommandline() { List commands = new LinkedList(); @@ -273,8 +278,8 @@ public class Commandline implements Cloneable { } /** - * add the entire command, including (optional) executable to a list - * @param list + * Add the entire command, including (optional) executable to a list. + * @param list ListIterator. * @since Ant 1.6 */ public void addCommandToList(ListIterator list) { @@ -284,10 +289,10 @@ public class Commandline implements Cloneable { addArgumentsToList(list); } - /** * Returns all arguments defined by addLine, * addValue or the argument object. + * @return String[]. */ public String[] getArguments() { List result = new ArrayList(arguments.size() * 2); @@ -297,8 +302,8 @@ public class Commandline implements Cloneable { } /** - * append all the arguments to the tail of a supplied list - * @param list + * Append all the arguments to the tail of a supplied list. + * @param list ListIterator. * @since Ant 1.6 */ public void addArgumentsToList(ListIterator list) { @@ -313,10 +318,9 @@ public class Commandline implements Cloneable { } } - /** - * stringify operator returns the command line as a string - * @return the command line + * Return the command line as a string. + * @return the command line. */ public String toString() { return toString(getCommandline()); @@ -329,6 +333,7 @@ public class Commandline implements Cloneable { * as is. If it contains double quotes, use single quotes - else * surround the argument by double quotes.

* + * @param argument the String argument. * @exception BuildException if the argument contains both, single * and double quotes. */ @@ -348,17 +353,17 @@ public class Commandline implements Cloneable { } /** - * Quotes the parts of the given array in way that makes them + * Quote the parts of the given array in way that makes them * usable as command line arguments. + * @param line the String[] to quote. * @return empty string for null or no command, else every argument split - * by spaces and quoted by quoting rules + * by spaces and quoted by quoting rules. */ - public static String toString(String [] line) { + public static String toString(String[] line) { // empty path return empty string if (line == null || line.length == 0) { return ""; } - // path containing one or more elements final StringBuffer result = new StringBuffer(); for (int i = 0; i < line.length; i++) { @@ -371,17 +376,16 @@ public class Commandline implements Cloneable { } /** - * crack a command line - * @param toProcess the command line to process + * Crack a command line. + * @param toProcess the command line to process. * @return the command line broken into strings. - * An empty or null toProcess parameter results in a zero sized array + * An empty or null toProcess parameter results in a zero sized array. */ public static String[] translateCommandline(String toProcess) { if (toProcess == null || toProcess.length() == 0) { //no command? no string return new String[0]; } - // parse with a simple finite state machine final int normal = 0; @@ -429,24 +433,21 @@ public class Commandline implements Cloneable { break; } } - if (lastTokenHasBeenQuoted || current.length() != 0) { v.addElement(current.toString()); } - if (state == inQuote || state == inDoubleQuote) { throw new BuildException("unbalanced quotes in " + toProcess); } - String[] args = new String[v.size()]; v.copyInto(args); return args; } /** - * size operator. This actually creates the command line, so it is not + * Size operator. This actually creates the command line, so it is not * a zero cost operation. - * @return number of elements in the command, including the executable + * @return number of elements in the command, including the executable. */ public int size() { return getCommandline().length; @@ -467,7 +468,8 @@ public class Commandline implements Cloneable { } /** - * Clear out the whole command line. */ + * Clear out the whole command line. + */ public void clear() { executable = null; arguments.removeAllElements(); @@ -485,7 +487,7 @@ public class Commandline implements Cloneable { * Return a marker. * *

This marker can be used to locate a position on the - * commandline - to insert something for example - when all + * commandline--to insert something for example--when all * parameters have been set.

*/ public Marker createMarker() { @@ -493,10 +495,9 @@ public class Commandline implements Cloneable { } /** - * Returns a String that describes the command and arguments - * suitable for verbose output before a call to - * Runtime.exec(String[]) - * + * Return a String that describes the command and arguments suitable for + * verbose output before a call to Runtime.exec(String[]). + * @return String. * @since Ant 1.5 */ public String describeCommand() { @@ -504,10 +505,9 @@ public class Commandline implements Cloneable { } /** - * Returns a String that describes the arguments suitable for - * verbose output before a call to - * Runtime.exec(String[]) - * + * Return a String that describes the arguments suitable for + * verbose output before a call to Runtime.exec(String[]). + * @return String. * @since Ant 1.5 */ public String describeArguments() { @@ -515,10 +515,10 @@ public class Commandline implements Cloneable { } /** - * Returns a String that describes the command and arguments - * suitable for verbose output before a call to - * Runtime.exec(String[]) - * + * Return a String that describes the command and arguments suitable for + * verbose output before a call to Runtime.exec(String[]). + * @param line the Commandline to describe. + * @return String. * @since Ant 1.5 */ public static String describeCommand(Commandline line) { @@ -526,10 +526,10 @@ public class Commandline implements Cloneable { } /** - * Returns a String that describes the arguments suitable for - * verbose output before a call to - * Runtime.exec(String[]) - * + * Return a String that describes the arguments suitable for + * verbose output before a call to Runtime.exec(String[]). + * @param line the Commandline whose arguments to describe. + * @return String. * @since Ant 1.5 */ public static String describeArguments(Commandline line) { @@ -537,20 +537,20 @@ public class Commandline implements Cloneable { } /** - * Returns a String that describes the command and arguments - * suitable for verbose output before a call to - * Runtime.exec(String[]). + * Return a String that describes the command and arguments suitable for + * verbose output before a call to Runtime.exec(String[]). * *

This method assumes that the first entry in the array is the * executable to run.

* + * @param args the command to describe. + * @return String. * @since Ant 1.5 */ public static String describeCommand(String[] args) { if (args == null || args.length == 0) { return ""; } - StringBuffer buf = new StringBuffer("Executing \'"); buf.append(args[0]); buf.append("\'"); @@ -564,10 +564,10 @@ public class Commandline implements Cloneable { } /** - * Returns a String that describes the arguments suitable for - * verbose output before a call to - * Runtime.exec(String[]) - * + * Return a String that describes the arguments suitable for + * verbose output before a call to Runtime.exec(String[]). + * @param args the arguments to describe. + * @return String. * @since Ant 1.5 */ public static String describeArguments(String[] args) { @@ -575,11 +575,12 @@ public class Commandline implements Cloneable { } /** - * Returns a String that describes the arguments suitable for - * verbose output before a call to - * Runtime.exec(String[]) + * Return a String that describes the arguments suitable for + * verbose output before a call to Runtime.exec(String[]). * + * @param args the arguments to describe. * @param offset ignore entries before this index + * @return String. * * @since Ant 1.5 */ @@ -587,7 +588,6 @@ public class Commandline implements Cloneable { if (args == null || args.length <= offset) { return ""; } - StringBuffer buf = new StringBuffer("argument"); if (args.length > offset) { buf.append("s"); @@ -602,9 +602,9 @@ public class Commandline implements Cloneable { } /** - * get an iterator to the list - * @since ant1.7 - * @return an iterator + * Get an iterator to the arguments list. + * @since Ant 1.7 + * @return an Iterator. */ public Iterator iterator() { return arguments.iterator();