javadoc

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

src/main/org/apache/tools/ant/types/Assertions.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.
@@ -80,7 +80,7 @@ public class Assertions extends DataType implements Cloneable {
 
     /**
      * enable assertions
-     * @param assertion
+     * @param assertion an enable assertion nested element
      */
     public void addEnable(EnabledAssertion assertion) {
         checkChildrenAllowed();
@@ -89,7 +89,7 @@ public class Assertions extends DataType implements Cloneable {
 
     /**
      * disable assertions
-     * @param assertion
+     * @param assertion a disable assertion nested element
      */
     public void addDisable(DisabledAssertion assertion) {
         checkChildrenAllowed();
@@ -97,8 +97,10 @@ public class Assertions extends DataType implements Cloneable {
     }
 
     /**
-     * enable or disable system assertions
-     * @param enableSystemAssertions
+     * enable or disable system assertions.
+     * Default is not set (neither -enablesystemassersions or -disablesytemassertions
+     * are used on the command line).
+     * @param enableSystemAssertions if true enable system assertions
      */
     public void setEnableSystemAssertions(Boolean enableSystemAssertions) {
         checkAttributesAllowed();
@@ -112,6 +114,7 @@ public class Assertions extends DataType implements Cloneable {
      * have been set as well or child elements have been created and
      * thus override this method. if they do the must call
      * <code>super.setRefid</code>.</p>
+     * @param ref the reference to use
      */
     public void setRefid(Reference ref) {
         if (assertionList.size() > 0 || enableSystemAssertions != null) {
@@ -157,7 +160,7 @@ public class Assertions extends DataType implements Cloneable {
     /**
      * add the assertions to a list in a format suitable
      * for adding to a command line
-     * @param commandList
+     * @param commandList the command line to format
      */
     public void applyAssertions(List commandList) {
         getProject().log("Applying assertions", Project.MSG_DEBUG);
@@ -183,7 +186,7 @@ public class Assertions extends DataType implements Cloneable {
 
     /**
      * apply all the assertions to the command.
-     * @param command
+     * @param command the command line to format
      */
     public void applyAssertions(CommandlineJava command) {
         Assertions clause = getFinalReference();
@@ -246,7 +249,7 @@ public class Assertions extends DataType implements Cloneable {
      * This is not a full depth clone; the list of assertions is cloned,
      * but it does not clone the underlying assertions.
      * @return a cli
-     * @throws CloneNotSupportedException
+     * @throws CloneNotSupportedException if the super class does not support cloning
      */
     public Object clone() throws CloneNotSupportedException {
         Assertions that = (Assertions) super.clone();
@@ -264,7 +267,7 @@ public class Assertions extends DataType implements Cloneable {
 
         /**
          * name a class
-         * @param className
+         * @param className a class name
          */
         public void setClass(String className) {
             this.className = className;
@@ -272,7 +275,7 @@ public class Assertions extends DataType implements Cloneable {
 
         /**
          * name a package
-         * @param packageName
+         * @param packageName a package name
          */
         public void setPackage(String packageName) {
             this.packageName = packageName;

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

@@ -156,7 +156,7 @@ public class Commandline implements Cloneable {
 
         /**
          * Return the constituent parts of this Argument.
-         * @return String[].
+         * @return an array of strings.
          */
         public String[] getParts() {
             return parts;
@@ -185,9 +185,9 @@ public class Commandline implements Cloneable {
         /**
          * Return the number of arguments that preceded this marker.
          *
-         * <p>The name of the executable--if set--is counted as the
+         * <p>The name of the executable -- if set -- is counted as the
          * first argument.</p>
-         * @return <code>int</code>.
+         * @return the position of this marker.
          */
         public int getPosition() {
             if (realPos == -1) {
@@ -223,6 +223,7 @@ public class Commandline implements Cloneable {
      *
      * @param insertAtStart if true, the argument is inserted at the
      * beginning of the list of args, otherwise it is appended.
+     * @return an argument to be configured
      */
     public Argument createArgument(boolean insertAtStart) {
         Argument argument = new Argument();
@@ -267,7 +268,7 @@ public class Commandline implements Cloneable {
 
     /**
      * Return the executable and all defined arguments.
-     * @return <code>String[]</code>.
+     * @return the commandline as an array of strings.
      */
     public String[] getCommandline() {
         List commands = new LinkedList();
@@ -279,7 +280,7 @@ public class Commandline implements Cloneable {
 
     /**
      * Add the entire command, including (optional) executable to a list.
-     * @param list ListIterator.
+     * @param list the list to add to.
      * @since Ant 1.6
      */
     public void addCommandToList(ListIterator list) {
@@ -292,7 +293,7 @@ public class Commandline implements Cloneable {
     /**
      * Returns all arguments defined by <code>addLine</code>,
      * <code>addValue</code> or the argument object.
-     * @return <code>String[]</code>.
+     * @return the arguments as an array of strings.
      */
     public String[] getArguments() {
         List result = new ArrayList(arguments.size() * 2);
@@ -303,7 +304,7 @@ public class Commandline implements Cloneable {
 
     /**
      * Append all the arguments to the tail of a supplied list.
-     * @param list ListIterator.
+     * @param list the list of arguments.
      * @since Ant 1.6
      */
     public void addArgumentsToList(ListIterator list) {
@@ -332,8 +333,8 @@ public class Commandline implements Cloneable {
      * <p>If the argument doesn't include spaces or quotes, return it
      * as is. If it contains double quotes, use single quotes - else
      * surround the argument by double quotes.</p>
-     *
-     * @param argument the String argument.
+     * @param argument the argument to quote if necessary.
+     * @return the quoted argument.
      * @exception BuildException if the argument contains both, single
      *                           and double quotes.
      */
@@ -355,7 +356,7 @@ public class Commandline implements Cloneable {
     /**
      * Quote the parts of the given array in way that makes them
      * usable as command line arguments.
-     * @param line the String[] to quote.
+     * @param line the list of arguments to quote.
      * @return empty string for null or no command, else every argument split
      * by spaces and quoted by quoting rules.
      */
@@ -489,6 +490,7 @@ public class Commandline implements Cloneable {
      * <p>This marker can be used to locate a position on the
      * commandline--to insert something for example--when all
      * parameters have been set.</p>
+     * @return a marker
      */
     public Marker createMarker() {
         return new Marker(arguments.size());
@@ -497,7 +499,7 @@ public class Commandline implements Cloneable {
     /**
      * Return a String that describes the command and arguments suitable for
      * verbose output before a call to <code>Runtime.exec(String[])<code>.
-     * @return <code>String</code>.
+     * @return a string that describes the command and arguments.
      * @since Ant 1.5
      */
     public String describeCommand() {
@@ -507,7 +509,7 @@ public class Commandline implements Cloneable {
     /**
      * Return a String that describes the arguments suitable for
      * verbose output before a call to <code>Runtime.exec(String[])<code>.
-     * @return <code>String</code>.
+     * @return a string that describes the arguments.
      * @since Ant 1.5
      */
     public String describeArguments() {
@@ -518,7 +520,7 @@ public class Commandline implements Cloneable {
      * Return a String that describes the command and arguments suitable for
      * verbose output before a call to <code>Runtime.exec(String[])<code>.
      * @param line the Commandline to describe.
-     * @return <code>String</code>.
+     * @return a string that describes the command and arguments.
      * @since Ant 1.5
      */
     public static String describeCommand(Commandline line) {
@@ -529,7 +531,7 @@ public class Commandline implements Cloneable {
      * Return a String that describes the arguments suitable for
      * verbose output before a call to <code>Runtime.exec(String[])<code>.
      * @param line the Commandline whose arguments to describe.
-     * @return <code>String</code>.
+     * @return a string that describes the arguments.
      * @since Ant 1.5
      */
     public static String describeArguments(Commandline line) {
@@ -542,9 +544,8 @@ public class Commandline implements Cloneable {
      *
      * <p>This method assumes that the first entry in the array is the
      * executable to run.</p>
-     *
-     * @param args the command to describe.
-     * @return <code>String</code>.
+     * @param args the command line to describe as an array of strings
+     * @return a string that describes the command and arguments.
      * @since Ant 1.5
      */
     public static String describeCommand(String[] args) {
@@ -566,8 +567,8 @@ public class Commandline implements Cloneable {
     /**
      * Return a String that describes the arguments suitable for
      * verbose output before a call to <code>Runtime.exec(String[])<code>.
-     * @param args the arguments to describe.
-     * @return <code>String</code>.
+     * @param args the command line to describe as an array of strings.
+     * @return a string that describes the arguments.
      * @since Ant 1.5
      */
     public static String describeArguments(String[] args) {
@@ -578,9 +579,9 @@ public class Commandline implements Cloneable {
      * Return a String that describes the arguments suitable for
      * verbose output before a call to <code>Runtime.exec(String[])<code>.
      *
-     * @param args the arguments to describe.
-     * @param offset ignore entries before this index
-     * @return <code>String</code>.
+     * @param args the command line to describe as an array of strings.
+     * @param offset ignore entries before this index.
+     * @return a string that describes the arguments
      *
      * @since Ant 1.5
      */

src/main/org/apache/tools/ant/types/DataType.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.
@@ -69,6 +69,7 @@ public abstract class DataType extends ProjectComponent {
     /**
      * Sets a description of the current data type. It will be useful
      * in commenting what we are doing.
+     * @param desc the desciption
      */
     public void setDescription(final String desc) {
         description = desc;
@@ -76,6 +77,7 @@ public abstract class DataType extends ProjectComponent {
 
     /**
      * Return the description for the current data type.
+     * @return the description
      */
     public String getDescription() {
         return description;
@@ -83,6 +85,7 @@ public abstract class DataType extends ProjectComponent {
 
     /**
      * Has the refid attribute of this element been set?
+     * @return true if the refid attribute has been set
      */
     public boolean isReference() {
         return ref != null;
@@ -95,6 +98,7 @@ public abstract class DataType extends ProjectComponent {
      * have been set as well or child elements have been created and
      * thus override this method. if they do the must call
      * <code>super.setRefid</code>.</p>
+     * @param ref the reference to use
      */
     public void setRefid(final Reference ref) {
         this.ref = ref;
@@ -116,6 +120,9 @@ public abstract class DataType extends ProjectComponent {
      * <p>The general contract of this method is that it shouldn't do
      * anything if {@link #checked <code>checked</code>} is true and
      * set it to true on exit.</p>
+     * @param stack the stack of references to check
+     * @param project the project to use to dereference the references
+     * @throws BuildException on error
      */
     protected void dieOnCircularReference(final Stack stack,
                                           final Project project)
@@ -141,6 +148,10 @@ public abstract class DataType extends ProjectComponent {
     /**
      * Performs the check for circular references and returns the
      * referenced object.
+     * @param requiredClass the class that this reference should be a subclass of
+     * @param dataTypeName  the name of the datatype that the reference should be (error message
+     *                      use only)
+     * @return the derefenced object
      */
     protected Object getCheckedRef(final Class requiredClass,
                                    final String dataTypeName) {
@@ -164,6 +175,7 @@ public abstract class DataType extends ProjectComponent {
     /**
      * Creates an exception that indicates that refid has to be the
      * only attribute if it is set.
+     * @return the exception to throw
      */
     protected BuildException tooManyAttributes() {
         return new BuildException("You must not specify more than one "
@@ -173,6 +185,7 @@ public abstract class DataType extends ProjectComponent {
     /**
      * Creates an exception that indicates that this XML element must
      * not have child elements if the refid attribute is set.
+     * @return the exception to throw
      */
     protected BuildException noChildrenAllowed() {
         return new BuildException("You must not specify nested elements "
@@ -182,16 +195,25 @@ public abstract class DataType extends ProjectComponent {
     /**
      * Creates an exception that indicates the user has generated a
      * loop of data types referencing each other.
+     * @return the exception to throw
      */
     protected BuildException circularReference() {
         return new BuildException("This data type contains a circular "
             + "reference.");
     }
 
+    /**
+     * The flag that is used to indicate that circular references have been checked.
+     * @return true if circular references have been checked
+     */
     protected boolean isChecked() {
         return checked;
     }
 
+    /**
+     * Set the flag that is used to indicate that circular references have been checked.
+     * @param checked if true, if circular references have been checked
+     */
     protected void setChecked(final boolean checked) {
         this.checked = checked;
     }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000-2002,2004 The Apache Software Foundation
+ * Copyright  2000-2002,2004-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.
@@ -54,6 +54,8 @@ public abstract class EnumeratedAttribute {
 
     /**
      * Invoked by {@link org.apache.tools.ant.IntrospectionHelper IntrospectionHelper}.
+     * @param value the <code>String</code> value of the attribute
+     * @throws BuildException if the value is not valid for the attribute
      */
     public final void setValue(String value) throws BuildException {
         int idx = indexOfValue(value);
@@ -66,6 +68,8 @@ public abstract class EnumeratedAttribute {
 
     /**
      * Is this value included in the enumeration?
+     * @param value the <code>String</code> value to look up
+     * @return true if the value is valid
      */
     public final boolean containsValue(String value) {
         return (indexOfValue(value) != -1);

src/main/org/apache/tools/ant/types/FileSet.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.
@@ -24,10 +24,17 @@ package org.apache.tools.ant.types;
  */
 public class FileSet extends AbstractFileSet {
 
+    /**
+     * Constructor for FileSet.
+     */
     public FileSet() {
         super();
     }
 
+    /**
+     * Constructor for FileSet, with FileSet to shallowly clone.
+     * @param fileset the fileset to clone
+     */
     protected FileSet(FileSet fileset) {
         super(fileset);
     }
@@ -35,6 +42,7 @@ public class FileSet extends AbstractFileSet {
     /**
      * Return a FileSet that has the same basedir and same patternsets
      * as this one.
+     * @return the cloned fileset
      */
     public Object clone() {
         if (isReference()) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright  2002,2004 The Apache Software Foundation
+ * Copyright  2002,2004-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.
@@ -29,6 +29,7 @@ public class FlexInteger {
 
     /**
      * Constructor used by Ant's introspection mechanism for attribute population
+     * @param value the value to decode
      */
     public FlexInteger(String value) {
         this.value = Integer.decode(value);
@@ -36,6 +37,7 @@ public class FlexInteger {
 
     /**
      * Returns the decimal integer value
+     * @return the integer value
      */
     public int intValue() {
         return value.intValue();
@@ -43,6 +45,7 @@ public class FlexInteger {
 
     /**
      * Overridden method to return the decimal value for display
+     * @return a string version of the integer
      */
     public String toString() {
         return value.toString();