From 1cf2b06dc35e0efd88629865e4073813ec210d84 Mon Sep 17 00:00:00 2001 From: Peter Reilly Date: Fri, 11 Mar 2005 10:12:07 +0000 Subject: [PATCH] javadoc git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@277896 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/tools/ant/types/Assertions.java | 23 +++++----- .../apache/tools/ant/types/Commandline.java | 45 ++++++++++--------- .../org/apache/tools/ant/types/DataType.java | 24 +++++++++- .../tools/ant/types/EnumeratedAttribute.java | 6 ++- .../org/apache/tools/ant/types/FileSet.java | 10 ++++- .../apache/tools/ant/types/FlexInteger.java | 5 ++- 6 files changed, 77 insertions(+), 36 deletions(-) diff --git a/src/main/org/apache/tools/ant/types/Assertions.java b/src/main/org/apache/tools/ant/types/Assertions.java index 4578dc573..ad9954d76 100644 --- a/src/main/org/apache/tools/ant/types/Assertions.java +++ b/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 * super.setRefid.

+ * @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; diff --git a/src/main/org/apache/tools/ant/types/Commandline.java b/src/main/org/apache/tools/ant/types/Commandline.java index 041dfe6a4..4330755c5 100644 --- a/src/main/org/apache/tools/ant/types/Commandline.java +++ b/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. * - *

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

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

- * @return int. + * @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 String[]. + * @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 addLine, * addValue or the argument object. - * @return String[]. + * @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 { *

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.

- * - * @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 { *

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

+ * @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 Runtime.exec(String[]). - * @return String. + * @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 Runtime.exec(String[]). - * @return String. + * @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 Runtime.exec(String[]). * @param line the Commandline to describe. - * @return String. + * @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 Runtime.exec(String[]). * @param line the Commandline whose arguments to describe. - * @return String. + * @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 { * *

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

- * - * @param args the command to describe. - * @return String. + * @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 Runtime.exec(String[]). - * @param args the arguments to describe. - * @return String. + * @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 Runtime.exec(String[]). * - * @param args the arguments to describe. - * @param offset ignore entries before this index - * @return String. + * @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 */ diff --git a/src/main/org/apache/tools/ant/types/DataType.java b/src/main/org/apache/tools/ant/types/DataType.java index 7f265fef5..23693db29 100644 --- a/src/main/org/apache/tools/ant/types/DataType.java +++ b/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 * super.setRefid.

+ * @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 { *

The general contract of this method is that it shouldn't do * anything if {@link #checked checked} is true and * set it to true on exit.

+ * @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; } diff --git a/src/main/org/apache/tools/ant/types/EnumeratedAttribute.java b/src/main/org/apache/tools/ant/types/EnumeratedAttribute.java index e7a288e24..3364d912a 100644 --- a/src/main/org/apache/tools/ant/types/EnumeratedAttribute.java +++ b/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 String 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 String value to look up + * @return true if the value is valid */ public final boolean containsValue(String value) { return (indexOfValue(value) != -1); diff --git a/src/main/org/apache/tools/ant/types/FileSet.java b/src/main/org/apache/tools/ant/types/FileSet.java index df765d4a9..53d0e0d8b 100644 --- a/src/main/org/apache/tools/ant/types/FileSet.java +++ b/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()) { diff --git a/src/main/org/apache/tools/ant/types/FlexInteger.java b/src/main/org/apache/tools/ant/types/FlexInteger.java index b508d5c95..ec9367185 100644 --- a/src/main/org/apache/tools/ant/types/FlexInteger.java +++ b/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();