Javadoc and LOC bumming

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

src/main/org/apache/tools/ant/types/AbstractFileSet.java

@@ -66,10 +66,18 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     private boolean isCaseSensitive = true;
     private boolean followSymlinks = true;
 
+    /**
+     * Construct a new <code>AbstractFileSet</code>.
+     */
     public AbstractFileSet() {
         super();
     }
 
+    /**
+     * Construct a new <code>AbstractFileSet</code>, shallowly cloned
+     * from the specified <code>AbstractFileSet</code>.
+     * @param fileset the <code>AbstractFileSet</code> to use as a template.
+     */
     protected AbstractFileSet(AbstractFileSet fileset) {
         this.dir = fileset.dir;
         this.defaultPatterns = fileset.defaultPatterns;
@@ -86,6 +94,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
      *
      * <p>You must not set another attribute or nest elements inside
      * this element if you make it a reference.</p>
+     * @param r the <code>Reference</code> to use.
      */
     public void setRefid(Reference r) throws BuildException {
         if (dir != null || defaultPatterns.hasPatterns(getProject())) {
@@ -102,17 +111,20 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
 
     /**
      * Sets the base-directory for this instance.
+     * @param dir the directory's <code>File</code> instance.
      */
     public void setDir(File dir) throws BuildException {
         if (isReference()) {
             throw tooManyAttributes();
         }
-
         this.dir = dir;
     }
 
     /**
      * Retrieves the base-directory for this instance.
+     * @param p the <code>Project</code> against which the
+     *          reference is resolved, if set.
+     * @return <code>File</code>.
      */
     public File getDir(Project p) {
         if (isReference()) {
@@ -123,6 +135,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
 
     /**
      * Creates a nested patternset.
+     * @return <code>PatternSet</code>.
      */
     public PatternSet createPatternSet() {
         if (isReference()) {
@@ -134,7 +147,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     }
 
     /**
-     * add a name entry on the include list
+     * Add a name entry to the include list.
+     * @return <code>PatternSet.NameEntry</code>.
      */
     public PatternSet.NameEntry createInclude() {
         if (isReference()) {
@@ -144,7 +158,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     }
 
     /**
-     * add a name entry on the include files list
+     * Add a name entry to the include files list.
+     * @return <code>PatternSet.NameEntry</code>.
      */
     public PatternSet.NameEntry createIncludesFile() {
         if (isReference()) {
@@ -154,7 +169,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     }
 
     /**
-     * add a name entry on the exclude list
+     * Add a name entry to the exclude list.
+     * @return <code>PatternSet.NameEntry</code>.
      */
     public PatternSet.NameEntry createExclude() {
         if (isReference()) {
@@ -164,7 +180,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     }
 
     /**
-     * add a name entry on the excludes files list
+     * Add a name entry to the excludes files list.
+     * @return <code>PatternSet.NameEntry</code>.
      */
     public PatternSet.NameEntry createExcludesFile() {
         if (isReference()) {
@@ -175,15 +192,15 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
 
     /**
      * Creates a single file fileset.
+     * @param file the single <code>File</code> included in this
+     *             <code>AbstractFileSet</code>.
      */
     public void setFile(File file) {
         if (isReference()) {
             throw tooManyAttributes();
         }
         setDir(file.getParentFile());
-
-        PatternSet.NameEntry include = createInclude();
-        include.setName(file.getName());
+        createInclude().setName(file.getName());
     }
 
     /**
@@ -192,13 +209,12 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
      *
      * <p>Patterns may be separated by a comma or a space.</p>
      *
-     * @param includes the string containing the include patterns
+     * @param includes the <code>String</code> containing the include patterns.
      */
     public void setIncludes(String includes) {
         if (isReference()) {
             throw tooManyAttributes();
         }
-
         defaultPatterns.setIncludes(includes);
     }
 
@@ -208,62 +224,55 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
      *
      * <p>Patterns may be separated by a comma or a space.</p>
      *
-     * @param excludes the string containing the exclude patterns
+     * @param excludes the <code>String</code> containing the exclude patterns.
      */
     public void setExcludes(String excludes) {
         if (isReference()) {
             throw tooManyAttributes();
         }
-
         defaultPatterns.setExcludes(excludes);
     }
 
     /**
-     * Sets the name of the file containing the includes patterns.
+     * Sets the <code>File</code> containing the includes patterns.
      *
-     * @param incl The file to fetch the include patterns from.
+     * @param incl <code>File</code> instance.
      */
      public void setIncludesfile(File incl) throws BuildException {
          if (isReference()) {
              throw tooManyAttributes();
          }
-
          defaultPatterns.setIncludesfile(incl);
      }
 
     /**
-     * Sets the name of the file containing the excludes patterns.
+     * Sets the <code>File</code> containing the excludes patterns.
      *
-     * @param excl The file to fetch the exclude patterns from.
+     * @param excl <code>File</code> instance.
      */
      public void setExcludesfile(File excl) throws BuildException {
          if (isReference()) {
              throw tooManyAttributes();
          }
-
          defaultPatterns.setExcludesfile(excl);
      }
 
     /**
      * Sets whether default exclusions should be used or not.
      *
-     * @param useDefaultExcludes "true"|"on"|"yes" when default exclusions
-     *                           should be used, "false"|"off"|"no" when they
-     *                           shouldn't be used.
+     * @param useDefaultExcludes <code>boolean</code>.
      */
     public void setDefaultexcludes(boolean useDefaultExcludes) {
         if (isReference()) {
             throw tooManyAttributes();
         }
-
         this.useDefaultExcludes = useDefaultExcludes;
     }
 
     /**
-     * Sets case sensitivity of the file system
+     * Sets case sensitivity of the file system.
      *
-     * @param isCaseSensitive "true"|"on"|"yes" if file system is case
-     *                           sensitive, "false"|"off"|"no" when not.
+     * @param isCaseSensitive <code>boolean</code>.
      */
     public void setCaseSensitive(boolean isCaseSensitive) {
         if (isReference()) {
@@ -275,7 +284,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     /**
      * Sets 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) {
         if (isReference()) {
@@ -285,22 +294,21 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     }
 
     /**
-     * find out if the fileset wants to follow symbolic links
+     * Find out if the fileset wants to follow symbolic links.
      *
-     * @return  flag indicating whether or not symbolic links should be followed
+     * @return <code>boolean</code> indicating whether symbolic links
+     *         should be followed.
      *
-     * @since ant 1.6
+     * @since Ant 1.6
      */
     public boolean isFollowSymlinks() {
-        if (isReference()) {
-            return getRef(getProject()).isFollowSymlinks();
-        } else {
-            return followSymlinks;
-        }
+        return (isReference())
+            ? getRef(getProject()).isFollowSymlinks() : followSymlinks;
     }
 
     /**
-     * sets the name used for this datatype instance.
+     * Gets as descriptive as possible a name used for this datatype instance.
+     * @return <code>String</code> name.
      */
     protected String getDataTypeName() {
         // look up the types in project and see if they match this class
@@ -315,29 +323,22 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
                 }
             }
         }
-
         String classname = getClass().getName();
-
-        int dotIndex = classname.lastIndexOf(".");
-        if (dotIndex == -1) {
-            return classname;
-        }
-        return classname.substring(dotIndex + 1);
+        return classname.substring(classname.lastIndexOf('.') + 1);
     }
 
     /**
      * Returns the directory scanner needed to access the files to process.
+     * @return a <code>DirectoryScanner</code> instance.
      */
     public DirectoryScanner getDirectoryScanner(Project p) {
         if (isReference()) {
             return getRef(p).getDirectoryScanner(p);
         }
-
         if (dir == null) {
             throw new BuildException("No directory specified for "
                                      + getDataTypeName() + ".");
         }
-
         if (!dir.exists()) {
             throw new BuildException(dir.getAbsolutePath() + " not found.");
         }
@@ -345,7 +346,6 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
             throw new BuildException(dir.getAbsolutePath()
                                      + " is not a directory.");
         }
-
         DirectoryScanner ds = new DirectoryScanner();
         setupDirectoryScanner(ds, p);
         ds.setFollowSymlinks(followSymlinks);
@@ -353,16 +353,19 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
         return ds;
     }
 
+    /**
+     * Set up the specified directory scanner against the specified project.
+     * @param ds a <code>FileScanner</code> instance.
+     * @param p an Ant <code>Project</code> instance.
+     */
     public void setupDirectoryScanner(FileScanner ds, Project p) {
         if (isReference()) {
             getRef(p).setupDirectoryScanner(ds, p);
             return;
         }
-
         if (ds == null) {
             throw new IllegalArgumentException("ds cannot be null");
         }
-
         ds.setBasedir(dir);
 
         final int count = additionalPatterns.size();
@@ -370,7 +373,6 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
             Object o = additionalPatterns.elementAt(i);
             defaultPatterns.append((PatternSet) o, p);
         }
-
         p.log(getDataTypeName() + ": Setup scanner in dir " + dir
             + " with " + defaultPatterns, Project.MSG_DEBUG);
 
@@ -380,7 +382,6 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
             SelectorScanner ss = (SelectorScanner) ds;
             ss.setSelectors(getSelectors(p));
         }
-
         if (useDefaultExcludes) {
             ds.addDefaultExcludes();
         }
@@ -397,7 +398,6 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
             stk.push(this);
             dieOnCircularReference(stk, p);
         }
-
         Object o = getRefid().getReferencedObject(p);
         if (!getClass().isAssignableFrom(o.getClass())) {
             String msg = getRefid().getRefId() + " doesn\'t denote a "
@@ -413,7 +413,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     /**
      * Indicates whether there are any selectors here.
      *
-     * @return whether any selectors are in this container
+     * @return whether any selectors are in this container.
      */
     public boolean hasSelectors() {
         if (isReference() && getProject() != null) {
@@ -425,17 +425,15 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     /**
      * Indicates whether there are any patterns here.
      *
-     * @return whether any patterns are in this container
+     * @return whether any patterns are in this container.
      */
     public boolean hasPatterns() {
         if (isReference() && getProject() != null) {
             return getRef(getProject()).hasPatterns();
         }
-
         if (defaultPatterns.hasPatterns(getProject())) {
             return true;
         }
-
         Enumeration e = additionalPatterns.elements();
         while (e.hasMoreElements()) {
             PatternSet ps = (PatternSet) e.nextElement();
@@ -443,14 +441,13 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
                 return true;
             }
         }
-
         return false;
     }
 
     /**
-     * Gives the count of the number of selectors in this container
+     * Gives the count of the number of selectors in this container.
      *
-     * @return the number of selectors in this container
+     * @return the number of selectors in this container as an <code>int</code>.
      */
     public int selectorCount() {
         if (isReference() && getProject() != null) {
@@ -462,22 +459,20 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     /**
      * Returns the set of selectors as an array.
      *
-     * @return an array of selectors in this container
+     * @return a <code>FileSelector[]</code> of the selectors in this container.
      */
     public FileSelector[] getSelectors(Project p) {
         if (isReference()) {
             return getRef(p).getSelectors(p);
-        } else {
-            FileSelector[] result = new FileSelector[selectors.size()];
-            selectors.copyInto(result);
-            return result;
         }
+        return (FileSelector[])(selectors.toArray(
+            new FileSelector[selectors.size()]));
     }
 
     /**
      * Returns an enumerator for accessing the set of selectors.
      *
-     * @return an enumerator that goes through each of the selectors
+     * @return an <code>Enumeration</code> of selectors.
      */
     public Enumeration selectorElements() {
         if (isReference() && getProject() != null) {
@@ -489,7 +484,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     /**
      * Add a new selector into this container.
      *
-     * @param selector the new selector to add
+     * @param selector the new <code>FileSelector</code> to add.
      */
     public void appendSelector(FileSelector selector) {
         if (isReference()) {
@@ -501,144 +496,144 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     /* Methods below all add specific selectors */
 
     /**
-     * add a "Select" selector entry on the selector list
-     * @param selector the selector to add
+     * Add a "Select" selector entry on the selector list.
+     * @param selector the <code>SelectSelector</code> to add.
      */
     public void addSelector(SelectSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add an "And" selector entry on the selector list
-     * @param selector the selector to add
+     * Add an "And" selector entry on the selector list.
+     * @param selector the <code>AndSelector</code> to add.
      */
     public void addAnd(AndSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add an "Or" selector entry on the selector list
-     * @param selector the selector to add
+     * Add an "Or" selector entry on the selector list.
+     * @param selector the <code>OrSelector</code> to add.
      */
     public void addOr(OrSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a "Not" selector entry on the selector list
-     * @param selector the selector to add
+     * Add a "Not" selector entry on the selector list.
+     * @param selector the <code>NotSelector</code> to add.
      */
     public void addNot(NotSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a "None" selector entry on the selector list
-     * @param selector the selector to add
+     * Add a "None" selector entry on the selector list.
+     * @param selector the <code>NoneSelector</code> to add.
      */
     public void addNone(NoneSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a majority selector entry on the selector list
-     * @param selector the selector to add
+     * Add a majority selector entry on the selector list.
+     * @param selector the <code>MajoritySelector</code> to add.
      */
     public void addMajority(MajoritySelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a selector date entry on the selector list
-     * @param selector the selector to add
+     * Add a selector date entry on the selector list.
+     * @param selector the <code>DateSelector</code> to add.
      */
     public void addDate(DateSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a selector size entry on the selector list
-     * @param selector the selector to add
+     * Add a selector size entry on the selector list.
+     * @param selector the <code>SizeSelector</code> to add.
      */
     public void addSize(SizeSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a DifferentSelector entry on the selector list
-     * @param selector the selector to add
+     * Add a DifferentSelector entry on the selector list.
+     * @param selector the <code>DifferentSelector</code> to add.
      */
     public void addDifferent(DifferentSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a selector filename entry on the selector list
-     * @param selector the selector to add
+     * Add a selector filename entry on the selector list.
+     * @param selector the <code>FilenameSelector</code> to add.
      */
     public void addFilename(FilenameSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a selector type entry on the selector list
-     * @param selector the selector to add
+     * Add a selector type entry on the selector list.
+     * @param selector the <code>TypeSelector</code> to add.
      */
     public void addType(TypeSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add an extended selector entry on the selector list
-     * @param selector the selector to add
+     * Add an extended selector entry on the selector list.
+     * @param selector the <code>ExtendSelector</code> to add.
      */
     public void addCustom(ExtendSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a contains selector entry on the selector list
-     * @param selector the selector to add
+     * Add a contains selector entry on the selector list.
+     * @param selector the <code>ContainsSelector</code> to add.
      */
     public void addContains(ContainsSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a present selector entry on the selector list
-     * @param selector the selector to add
+     * Add a present selector entry on the selector list.
+     * @param selector the <code>PresentSelector</code> to add.
      */
     public void addPresent(PresentSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a depth selector entry on the selector list
-     * @param selector the selector to add
+     * Add a depth selector entry on the selector list.
+     * @param selector the <code>DepthSelector</code> to add.
      */
     public void addDepth(DepthSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a depends selector entry on the selector list
-     * @param selector the selector to add
+     * Add a depends selector entry on the selector list.
+     * @param selector the <code>DependSelector</code> to add.
      */
     public void addDepend(DependSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add a regular expression selector entry on the selector list
-     * @param selector the selector to add
+     * Add a regular expression selector entry on the selector list.
+     * @param selector the <code>ContainsRegexpSelector</code> to add.
      */
     public void addContainsRegexp(ContainsRegexpSelector selector) {
         appendSelector(selector);
     }
 
     /**
-     * add the modified selector
-     * @param selector the selector to add
+     * Add the modified selector.
+     * @param selector the <code>ModifiedSelector</code> to add.
      * @since ant 1.6
      */
     public void addModified(ModifiedSelector selector) {
@@ -646,8 +641,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     }
 
     /**
-     * add an arbitary selector
-     * @param selector the selector to add
+     * Add an arbitary selector.
+     * @param selector the <code>FileSelector</code> to add.
      * @since Ant 1.6
      */
     public void add(FileSelector selector) {
@@ -655,9 +650,9 @@ public abstract class AbstractFileSet extends DataType implements Cloneable,
     }
 
     /**
-     * Returns included files as a list of semicolon-separated filenames
+     * Returns included files as a list of semicolon-separated filenames.
      *
-     * @return String object with included filenames
+     * @return a <code>String</code> of included filenames.
      */
     public String toString() {
         DirectoryScanner ds = getDirectoryScanner(getProject());