From 69c95afa02d8a3f629053c2dbef24ff386aabc07 Mon Sep 17 00:00:00 2001 From: "Jesse N. Glick" Date: Fri, 18 Aug 2006 20:07:32 +0000 Subject: [PATCH] Some Javadoc corrections. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@432709 13f79535-47bb-0310-9956-ffa450edef68 --- src/main/org/apache/tools/ant/Main.java | 4 ++-- .../org/apache/tools/ant/launch/Locator.java | 2 +- .../ant/taskdefs/AbstractJarSignerTask.java | 2 +- .../apache/tools/ant/taskdefs/AntStructure.java | 8 +++----- .../org/apache/tools/ant/taskdefs/Expand.java | 2 +- .../apache/tools/ant/taskdefs/RecorderEntry.java | 14 +++++++------- src/main/org/apache/tools/ant/taskdefs/Tar.java | 4 ++-- .../org/apache/tools/ant/taskdefs/Untar.java | 4 ++-- src/main/org/apache/tools/ant/taskdefs/Zip.java | 2 +- .../ant/taskdefs/condition/ParserSupports.java | 5 ----- .../ant/taskdefs/condition/ResourcesMatch.java | 2 +- .../ant/taskdefs/optional/SchemaValidate.java | 16 ++++++---------- .../ant/taskdefs/optional/dotnet/CSharp.java | 6 ------ .../taskdefs/optional/dotnet/DotnetCompile.java | 2 +- .../taskdefs/optional/dotnet/DotnetResource.java | 7 +++---- .../ant/taskdefs/optional/dotnet/JSharp.java | 6 ------ .../optional/dotnet/VisualBasicCompile.java | 6 ------ .../taskdefs/optional/dotnet/WsdlToDotnet.java | 16 ++++++++-------- .../org/apache/tools/ant/types/TarFileSet.java | 6 ------ .../types/optional/AbstractScriptComponent.java | 4 ++-- .../org/apache/tools/ant/util/FileUtils.java | 14 +++++++------- 21 files changed, 48 insertions(+), 84 deletions(-) diff --git a/src/main/org/apache/tools/ant/Main.java b/src/main/org/apache/tools/ant/Main.java index 9de15e7b8..d811c3cc3 100644 --- a/src/main/org/apache/tools/ant/Main.java +++ b/src/main/org/apache/tools/ant/Main.java @@ -218,8 +218,8 @@ public class Main implements AntMain { /** * This operation is expected to call {@link System#exit(int)}, which - * is what the base version does. however, the option to do something - * different is there. + * is what the base version does. + * However, it is possible to do something else. * @param exitCode code to exit with */ protected void exit(int exitCode) { diff --git a/src/main/org/apache/tools/ant/launch/Locator.java b/src/main/org/apache/tools/ant/launch/Locator.java index 635f60f8f..4a63b4dba 100644 --- a/src/main/org/apache/tools/ant/launch/Locator.java +++ b/src/main/org/apache/tools/ant/launch/Locator.java @@ -133,7 +133,7 @@ public final class Locator { *

Prior to Java 1.4, * swallows '%' that are not followed by two characters.

* - * @see dt-sysid + * See dt-sysid * which makes some mention of how * characters not supported by URI Reference syntax should be escaped. * diff --git a/src/main/org/apache/tools/ant/taskdefs/AbstractJarSignerTask.java b/src/main/org/apache/tools/ant/taskdefs/AbstractJarSignerTask.java index f51e0ef22..3248ea0ca 100644 --- a/src/main/org/apache/tools/ant/taskdefs/AbstractJarSignerTask.java +++ b/src/main/org/apache/tools/ant/taskdefs/AbstractJarSignerTask.java @@ -193,7 +193,7 @@ public abstract class AbstractJarSignerTask extends Task { /** * Adds a path of files to sign. * - * @param a path of files to sign. + * @return a path of files to sign. * @since Ant 1.7 */ public Path createPath() { diff --git a/src/main/org/apache/tools/ant/taskdefs/AntStructure.java b/src/main/org/apache/tools/ant/taskdefs/AntStructure.java index c06a20d80..76639f3e2 100644 --- a/src/main/org/apache/tools/ant/taskdefs/AntStructure.java +++ b/src/main/org/apache/tools/ant/taskdefs/AntStructure.java @@ -126,10 +126,8 @@ public class AntStructure extends Task { /** * Writes the actual structure information. * - *

{@link StructurePrinter#printHead printHead}, {@link - * StructurePrinter#printTargetDecl printTargetDecl} and {@link - * StructurePrinter#printTail printTail} are called exactly once, - * {@link StructurePrinter#printElement printElement} once for + *

{@link #printHead}, {@link #printTargetDecl} and {@link #printTail} + * are called exactly once, {@link #printElementDecl} once for * each declared task and type.

*/ public static interface StructurePrinter { @@ -157,7 +155,7 @@ public class AntStructure extends Task { * @param out PrintWriter to write to. * @param p Project instance for the current task * @param name element name. - * @param name class of the defined element. + * @param element class of the defined element. */ void printElementDecl(PrintWriter out, Project p, String name, Class element); diff --git a/src/main/org/apache/tools/ant/taskdefs/Expand.java b/src/main/org/apache/tools/ant/taskdefs/Expand.java index 90ba17873..18dc5b37d 100644 --- a/src/main/org/apache/tools/ant/taskdefs/Expand.java +++ b/src/main/org/apache/tools/ant/taskdefs/Expand.java @@ -153,7 +153,7 @@ public class Expand extends Task { /** * This method is to be overridden by extending unarchival tasks. * - * @param r the source resource + * @param srcR the source resource * @param dir the destination directory */ protected void expandResource(Resource srcR, File dir) { diff --git a/src/main/org/apache/tools/ant/taskdefs/RecorderEntry.java b/src/main/org/apache/tools/ant/taskdefs/RecorderEntry.java index bb0b527f5..2c9eaf87f 100644 --- a/src/main/org/apache/tools/ant/taskdefs/RecorderEntry.java +++ b/src/main/org/apache/tools/ant/taskdefs/RecorderEntry.java @@ -87,14 +87,14 @@ public class RecorderEntry implements BuildLogger, SubBuildListener { } /** - * @see BuildListener#buildStarted(BuildEvent) + * @see org.apache.tools.ant.BuildListener#buildStarted(BuildEvent) */ public void buildStarted(BuildEvent event) { log("> BUILD STARTED", Project.MSG_DEBUG); } /** - * @see BuildListener#buildFinished(BuildEvent) + * @see org.apache.tools.ant.BuildListener#buildFinished(BuildEvent) */ public void buildFinished(BuildEvent event) { log("< BUILD FINISHED", Project.MSG_DEBUG); @@ -139,7 +139,7 @@ public class RecorderEntry implements BuildLogger, SubBuildListener { } /** - * @see BuildListener#targetStarted(BuildEvent) + * @see org.apache.tools.ant.BuildListener#targetStarted(BuildEvent) */ public void targetStarted(BuildEvent event) { log(">> TARGET STARTED -- " + event.getTarget(), Project.MSG_DEBUG); @@ -149,7 +149,7 @@ public class RecorderEntry implements BuildLogger, SubBuildListener { } /** - * @see BuildListener#targetFinished(BuildEvent) + * @see org.apache.tools.ant.BuildListener#targetFinished(BuildEvent) */ public void targetFinished(BuildEvent event) { log("<< TARGET FINISHED -- " + event.getTarget(), Project.MSG_DEBUG); @@ -161,14 +161,14 @@ public class RecorderEntry implements BuildLogger, SubBuildListener { } /** - * @see BuildListener#taskStarted(BuildEvent) + * @see org.apache.tools.ant.BuildListener#taskStarted(BuildEvent) */ public void taskStarted(BuildEvent event) { log(">>> TASK STARTED -- " + event.getTask(), Project.MSG_DEBUG); } /** - * @see BuildListener#taskFinished(BuildEvent) + * @see org.apache.tools.ant.BuildListener#taskFinished(BuildEvent) */ public void taskFinished(BuildEvent event) { log("<<< TASK FINISHED -- " + event.getTask(), Project.MSG_DEBUG); @@ -176,7 +176,7 @@ public class RecorderEntry implements BuildLogger, SubBuildListener { } /** - * @see BuildListener#messageLogged(BuildEvent) + * @see org.apache.tools.ant.BuildListener#messageLogged(BuildEvent) */ public void messageLogged(BuildEvent event) { log("--- MESSAGE LOGGED", Project.MSG_DEBUG); diff --git a/src/main/org/apache/tools/ant/taskdefs/Tar.java b/src/main/org/apache/tools/ant/taskdefs/Tar.java index 76a53d491..f42f2ca2d 100644 --- a/src/main/org/apache/tools/ant/taskdefs/Tar.java +++ b/src/main/org/apache/tools/ant/taskdefs/Tar.java @@ -339,7 +339,7 @@ public class Tar extends MatchingTask { /** * tar a resource - * @param file the resource to tar + * @param r the resource to tar * @param tOut the output stream * @param vPath the path name of the file to tar * @param tarFileSet the fileset that the file came from, may be null. @@ -502,7 +502,7 @@ public class Tar extends MatchingTask { /** * Is the archive up to date in relationship to a list of files. - * @param files the files to check + * @param r the files to check * @return true if the archive is up to date. * @since Ant 1.7 */ diff --git a/src/main/org/apache/tools/ant/taskdefs/Untar.java b/src/main/org/apache/tools/ant/taskdefs/Untar.java index 6db0bb448..e6abb7dd0 100644 --- a/src/main/org/apache/tools/ant/taskdefs/Untar.java +++ b/src/main/org/apache/tools/ant/taskdefs/Untar.java @@ -106,7 +106,7 @@ public class Untar extends Expand { /** * This method is to be overridden by extending unarchival tasks. * - * @param r the source resource + * @param srcR the source resource * @param dir the destination directory * @since Ant 1.7 */ @@ -190,7 +190,7 @@ public class Untar extends Expand { * This method wraps the input stream with the * corresponding decompression method * - * @param file provides location information for BuildException + * @param name provides location information for BuildException * @param istream input stream * @return input stream with on-the-fly decompression * @exception IOException thrown by GZIPInputStream constructor diff --git a/src/main/org/apache/tools/ant/taskdefs/Zip.java b/src/main/org/apache/tools/ant/taskdefs/Zip.java index 653f7b905..5872b9729 100644 --- a/src/main/org/apache/tools/ant/taskdefs/Zip.java +++ b/src/main/org/apache/tools/ant/taskdefs/Zip.java @@ -1164,7 +1164,7 @@ public class Zip extends MatchingTask { * third arg if they already know that the archive is * out-of-date.

* - * @param filesets The filesets to grab resources from + * @param rcs The filesets to grab resources from * @param zipFile intended archive file (may or may not exist) * @param needsUpdate whether we already know that the archive is * out-of-date. Subclasses overriding this method are supposed to diff --git a/src/main/org/apache/tools/ant/taskdefs/condition/ParserSupports.java b/src/main/org/apache/tools/ant/taskdefs/condition/ParserSupports.java index 4266c7125..34c3afddf 100644 --- a/src/main/org/apache/tools/ant/taskdefs/condition/ParserSupports.java +++ b/src/main/org/apache/tools/ant/taskdefs/condition/ParserSupports.java @@ -73,11 +73,6 @@ public class ParserSupports extends ProjectComponent implements Condition { this.value = value; } - /** - * Validate the args, then try to set the feature or property - * @return - * @throws BuildException - */ public boolean eval() throws BuildException { if (feature != null && property != null) { throw new BuildException(ERROR_BOTH_ATTRIBUTES); diff --git a/src/main/org/apache/tools/ant/taskdefs/condition/ResourcesMatch.java b/src/main/org/apache/tools/ant/taskdefs/condition/ResourcesMatch.java index b4a2ffa35..27967f497 100644 --- a/src/main/org/apache/tools/ant/taskdefs/condition/ResourcesMatch.java +++ b/src/main/org/apache/tools/ant/taskdefs/condition/ResourcesMatch.java @@ -41,7 +41,7 @@ public class ResourcesMatch implements Condition { /** * Set whether to treat resources as if they were text files, * ignoring line endings. - * @param astext whether to ignore line endings. + * @param asText whether to ignore line endings. */ public void setAsText(boolean asText) { this.asText = asText; diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/SchemaValidate.java b/src/main/org/apache/tools/ant/taskdefs/optional/SchemaValidate.java index 5c17ba9dc..fee8acf40 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/SchemaValidate.java +++ b/src/main/org/apache/tools/ant/taskdefs/optional/SchemaValidate.java @@ -89,8 +89,8 @@ public class SchemaValidate extends XMLValidateTask { } /** - * turn on XSD support in Xerces - * @return + * Turn on XSD support in Xerces. + * @return true on success, false on failure */ public boolean enableXercesSchemaValidation() { try { @@ -116,10 +116,10 @@ public class SchemaValidate extends XMLValidateTask { } /** - * set schema attributes in a JAXP12 engine + * Set schema attributes in a JAXP 1.2 engine. * @see * JAXP 1.2 Approved CHANGES - * @return + * @return true on success, false on failure */ public boolean enableJAXP12SchemaValidation() { try { @@ -230,7 +230,7 @@ public class SchemaValidate extends XMLValidateTask { * Create a reader if the use of the class did not specify another one. * The reason to not use {@link JAXPUtils#getXMLReader()} was to * create our own factory with our own options. - * @return + * @return a default XML parser */ protected XMLReader createDefaultReader() { SAXParserFactory factory = SAXParserFactory.newInstance(); @@ -274,7 +274,7 @@ public class SchemaValidate extends XMLValidateTask { /** * get the URL of the no namespace schema - * @return + * @return the schema URL */ protected String getNoNamespaceSchemaURL() { if (anonymousSchema == null) { @@ -465,10 +465,6 @@ public class SchemaValidate extends XMLValidateTask { return true; } - /** - * hashcode function - * @return - */ public int hashCode() { int result; result = (namespace != null ? namespace.hashCode() : 0); diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/CSharp.java b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/CSharp.java index 7280a7cae..3c283abe5 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/CSharp.java +++ b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/CSharp.java @@ -380,12 +380,6 @@ public class CSharp extends DotnetCompile { return "cs"; } - /** - * from a resource, get the resource param string - * @param resource - * @return a string containing the resource param, or a null string - * to conditionally exclude a resource. - */ protected void createResourceParameter(NetCommand command, DotnetResource resource) { resource.getParameters(getProject(), command, true); } diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetCompile.java b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetCompile.java index 8cf0e0b48..7257ad1a6 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetCompile.java +++ b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetCompile.java @@ -874,7 +874,7 @@ public abstract class DotnetCompile } } - /** + /* XXX Javadoc makes little sense, rewrite * from a resource, get the * @param resource * @return a string containing the resource param, or a null string diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetResource.java b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetResource.java index 35c7f281e..0111da591 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetResource.java +++ b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetResource.java @@ -25,8 +25,9 @@ import java.util.Iterator; import org.apache.tools.ant.*; /** - * class used by DotnetCompile to name resources, could be upgraded to a - * datatype in the distant future. a resource maps to /res:file,name + * Used by {@link DotnetCompile} to name resources. + * Could be upgraded to a datatype in the distant future. + * A resource maps to /res:file,name */ public class DotnetResource { @@ -153,8 +154,6 @@ public class DotnetResource { /** * build the C# style parameter (which has no public/private option) - * - * @return the built C# style parameter */ public void getParameters(Project p, NetCommand command, boolean csharpStyle) { checkParameters(); diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/JSharp.java b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/JSharp.java index 5da6f2eeb..ab93cc662 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/JSharp.java +++ b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/JSharp.java @@ -113,12 +113,6 @@ public class JSharp extends DotnetCompile { } } - /** - * from a resource, get the resource param - * @param resource - * @return a string containing the resource param, or a null string - * to conditionally exclude a resource. - */ protected void createResourceParameter(NetCommand command, DotnetResource resource) { resource.getParameters(getProject(), command, true); } diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/VisualBasicCompile.java b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/VisualBasicCompile.java index e9704a2eb..0d36cfa5e 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/VisualBasicCompile.java +++ b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/VisualBasicCompile.java @@ -346,12 +346,6 @@ public class VisualBasicCompile extends DotnetCompile { return "vb"; } - /** - * from a resource, get the resource param - * @param resource - * @return a string containing the resource param, or a null string - * to conditionally exclude a resource. - */ protected void createResourceParameter(NetCommand command, DotnetResource resource) { resource.getParameters(getProject(), command, false); } diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/WsdlToDotnet.java b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/WsdlToDotnet.java index aaf543684..eae29e9ff 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/WsdlToDotnet.java +++ b/src/main/org/apache/tools/ant/taskdefs/optional/dotnet/WsdlToDotnet.java @@ -391,8 +391,8 @@ public class WsdlToDotnet extends Task { } /** - * validate our settings then return either the url or the full file path. - * @return + * Validate our settings. + * @return either the URL or the full file path */ public String evaluate() { validate(); @@ -448,8 +448,8 @@ public class WsdlToDotnet extends Task { } /** - * return the timestamp of a file, or -1 for a url (meaning we do not know its age) - * @return + * Gets the file timestamp. + * @return the timestamp of a file, or -1 for a URL (meaning we do not know its age) */ public long getTimestamp() { if (file != null) { @@ -513,8 +513,8 @@ public class WsdlToDotnet extends Task { } /** - * create the default compiler for this platform - * @return + * Create the default compiler for this platform. + * @return the default compiler */ public static Compiler createDefaultCompiler() { Compiler c = new Compiler(); @@ -526,7 +526,7 @@ public class WsdlToDotnet extends Task { /** * return the command to run - * @return + * @return the command */ public String getCommand() { return compilerExecutables[getIndex()]; @@ -534,7 +534,7 @@ public class WsdlToDotnet extends Task { /** * return any extra arguments for the compiler - * @return + * @return extra compiler arguments */ public String[] getExtraArgs() { return extraCompilerArgs[getIndex()]; diff --git a/src/main/org/apache/tools/ant/types/TarFileSet.java b/src/main/org/apache/tools/ant/types/TarFileSet.java index 76ad8c8b0..5cbf6b975 100755 --- a/src/main/org/apache/tools/ant/types/TarFileSet.java +++ b/src/main/org/apache/tools/ant/types/TarFileSet.java @@ -214,12 +214,6 @@ public class TarFileSet extends ArchiveFileSet { } } - /** - * A ArchiveFileset accepts another ArchiveFileSet or a FileSet as reference - * FileSets are often used by the war task for the lib attribute - * @param p the project to use - * @return the abstract fileset instance - */ protected void configureFileSet(ArchiveFileSet zfs) { super.configureFileSet(zfs); if (zfs instanceof TarFileSet) { diff --git a/src/main/org/apache/tools/ant/types/optional/AbstractScriptComponent.java b/src/main/org/apache/tools/ant/types/optional/AbstractScriptComponent.java index 97ad932c0..d69f43a30 100644 --- a/src/main/org/apache/tools/ant/types/optional/AbstractScriptComponent.java +++ b/src/main/org/apache/tools/ant/types/optional/AbstractScriptComponent.java @@ -33,8 +33,8 @@ public abstract class AbstractScriptComponent extends ProjectComponent { /** * Get our script runner - * @return - */ + * @return the runner + */ public ScriptRunner getRunner() { return runner; } diff --git a/src/main/org/apache/tools/ant/util/FileUtils.java b/src/main/org/apache/tools/ant/util/FileUtils.java index ced52a115..e570544a5 100644 --- a/src/main/org/apache/tools/ant/util/FileUtils.java +++ b/src/main/org/apache/tools/ant/util/FileUtils.java @@ -654,7 +654,7 @@ public class FileUtils { *
  • DOS style paths that start with a drive letter will have * \ as the separator.
    • * - * Unlike File#getCanonicalPath() this method + * Unlike {@link File#getCanonicalPath()} this method * specifically does not resolve symbolic links. * * @param path the path to be normalized. @@ -1072,7 +1072,7 @@ public class FileUtils { * *

    The coding of the output is the same as what File.toURI().toASCIIString() produces

    * - * @see dt-sysid + * See dt-sysid * which makes some mention of how * characters not supported by URI Reference syntax should be escaped. * @@ -1349,7 +1349,7 @@ public class FileUtils { } /** - * Calculates the relative path between to files. + * Calculates the relative path between two files. *

    * Implementation note:
    This function my throw an IOException if an * I/O error occurs because its use of the canonical pathname may require @@ -1360,9 +1360,9 @@ public class FileUtils { * the File to calculate the path from * @param toFile * the File to calculate the path to - * @return - * @throws Exception - * @see {@link File#getCanonicalPath()} + * @return the relative path between the files + * @throws Exception for undocumented reasons + * @see File#getCanonicalPath() * * @since Ant 1.7 */ @@ -1482,4 +1482,4 @@ public class FileUtils { return buffer.toString(); } -} \ No newline at end of file +}