- fixed errors reported by javadoc tool

- added html and body tags to package.html

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/cli/trunk@267495 13f79535-47bb-0310-9956-ffa450edef68

Author: John Keyes

src/java/org/apache/commons/cli2/Option.java

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright 2003-2005 The Apache Software Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -72,7 +72,7 @@ void process(
      * argument. The ListIterator must be restored to the initial state before
      * returning the boolean.
      * 
-     * @see #canProcess(String)
+     * @see #canProcess(WriteableCommandLine,String)
      * @param arguments
      *            the ListIterator over String arguments
      * @return true if the argument can be processed by this Option
@@ -118,7 +118,7 @@ void validate(final WriteableCommandLine commandLine)
      * Builds up a list of HelpLineImpl instances to be presented by HelpFormatter.
      * 
      * @see HelpLine
-     * @see HelpFormatter
+     * @see org.apache.commons.cli2.util.HelpFormatter
      * @param depth
      *            the initial indent depth
      * @param helpSettings
@@ -156,7 +156,7 @@ void appendUsage(
      * Returns a description of the option. This string is used to build help
      * messages as in the HelpFormatter.
      * 
-     * @see HelpFormatter
+     * @see org.apache.commons.cli2.util.HelpFormatter
      * @return a description of the option.
      */
     String getDescription();

src/java/org/apache/commons/cli2/builder/CommandBuilder.java

@@ -27,24 +27,37 @@
  */
 public class CommandBuilder {
 
+    /** the preferred name of the command */
     private String preferredName;
+
+    /** the description of the command */
     private String description;
+
+    /** the aliases of the command */
     private Set aliases;
+
+    /** whether the command is required or not */
     private boolean required;
+
+    /** the argument of the command */
     private Argument argument;
+
+    /** the children of the command */
     private Group children;
+
+    /** the id of the command */
     private int id;
 
     /**
-     * Creates a new CommandBuilder instance
+     * Creates a new <code>CommandBuilder</code> instance.
      */
     public CommandBuilder() {
         reset();
     }
 
     /**
-     * Creates a new Command instance using the properties of the
-     * CommandBuilder.
+     * Creates a new <code>Command</code> instance using the properties of the
+     * <code>CommandBuilder</code>.
      * 
      * @return the new Command instance
      */
@@ -73,8 +86,10 @@ public Command create() {
     }
 
     /**
-     * Resets the CommandBuilder to the defaults for a new Command. The method
-     * should be called automatically at the end of a create() call.
+     * Resets the CommandBuilder to the defaults for a new Command. 
+     * 
+     * This method is called automatically at the end of the
+     * {@link #create() create} method.
      */
     public CommandBuilder reset() {
         preferredName = null;
@@ -88,12 +103,14 @@ public CommandBuilder reset() {
     }
 
     /**
-     * Sets the name of the command. The first name is used as the preferred
-     * display name for the Command and then later names are used as aliases.
+     * Specifies the name for the next <code>Command</code> 
+     * that is created.  The first name is used as the preferred
+     * display name for the <code>Command</code> and then 
+     * later names are used as aliases.
      * 
-     * @param name
-     *            a name for the Command
-     * @return this CommandBuilder
+     * @param name the name for the next <code>Command</code>
+     * that is created.
+     * @return this <code>CommandBuilder</code>.
      */
     public CommandBuilder withName(final String name) {
         if (preferredName == null) {
@@ -107,58 +124,62 @@ public CommandBuilder withName(final String name) {
     }
 
     /**
-     * Sets the description of the command. The description is used to produce
-     * online help for the command.
+     * Specifies the description for the next <code>Command</code>
+     * that is created.  This description is used to produce 
+     * help documentation for the <code>Command</code>.
      * 
-     * @param newDescription
-     *            The description of the command
-     * @return this CommandBuilder
+     * @param newDescription the description for the next 
+     * <code>Command</code> that is created.
+     * @return this <code>CommandBuilder</code>.
      */
     public CommandBuilder withDescription(final String newDescription) {
         this.description = newDescription;
         return this;
     }
 
     /**
-     * Use this optionality
-     * @param newRequired true iff the Option is required
-     * @return this builder
+     * Specifies whether the next <code>Command</code> created is
+     * required or not.
+     * @param newRequired whether the next <code>Command</code> created is
+     * required or not.
+     * @return this <code>CommandBuilder</code>.
      */
     public CommandBuilder withRequired(final boolean newRequired) {
         this.required = newRequired;
         return this;
     }
 
     /**
-     * Sets the children of the Command.
+     * Specifies the children for the next <code>Command</code> 
+     * that is created.
      * 
-     * @param newChildren
-     *            the child options for the Command
-     * @return this CommandBuilder
+     * @param newChildren the child options for the next <code>Command</code>
+     * that is created.
+     * @return this <code>CommandBuilder</code>.
      */
     public CommandBuilder withChildren(final Group newChildren) {
         this.children = newChildren;
         return this;
     }
 
     /**
-     * Sets the argument of the Command.
+     * Specifies the argument for the next <code>Command</code> 
+     * that is created.
      * 
-     * @param newArgument
-     *            the argument for the Command
-     * @return this CommandBuilder
+     * @param newArgument the argument for the next <code>Command</code> 
+     * that is created.
+     * @return this <code>CommandBuilder</code>.
      */
     public CommandBuilder withArgument(final Argument newArgument) {
         this.argument = newArgument;
         return this;
     }
 
     /**
-     * Sets the id
+     * Specifies the id for the next <code>Command</code> that is created.
      * 
-     * @param newId
-     *            the id of the Command
-     * @return this CommandBuilder
+     * @param newId the id for the next <code>Command</code> that is created.
+     * @return this <code>CommandBuilder</code>.
      */
     public final CommandBuilder withId(final int newId) {
         this.id = newId;

src/java/org/apache/commons/cli2/option/ArgumentImpl.java

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright 2003-2005 The Apache Software Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -87,7 +87,7 @@ public class ArgumentImpl extends OptionImpl implements Argument {
      *            The object responsible for validating the values
      * @param consumeRemaining
      *            The String used for the "consuming option" group
-     * @param defaultValues
+     * @param valueDefaults
      *            The values to be used if none are specified.
      * @param id
      *            The id of the option, 0 implies automatic assignment.
@@ -124,7 +124,7 @@ public ArgumentImpl(
                 resources.getMessage("cli.error.minimum.exceeds.maximum"));
         }
 
-        if (valueDefaults != null) {
+        if (valueDefaults != null && valueDefaults.size() > 0) {
             if (valueDefaults.size() < minimum) {
                 throw new IllegalArgumentException(
                     resources.getMessage("cli.error.too.few.defaults"));

src/java/org/apache/commons/cli2/validation/ClassValidator.java

@@ -21,7 +21,24 @@
 import org.apache.commons.cli2.resource.ResourceHelper;
 
 /**
- * A validator checking for classnames
+ * The <code>ClassValidator</code> validates the string argument
+ * values are class names.
+ *
+ * The following example shows how to validate the 'logger'
+ * argument value is a class name, that can be instantiated.
+ *
+ * <pre>
+ * ...
+ * ClassValidator validator = new ClassValidator();
+ * validator.setInstance(true);
+ *
+ * ArgumentBuilder builder = new ArgumentBuilder();
+ * Argument logger = 
+ *     builder.withName("logger");
+ *            .withValidator(validator);
+ * </pre>
+ * 
+ * @author John Keyes
  */
 public class ClassValidator implements Validator {
 
@@ -156,7 +173,7 @@ public boolean isInstance() {
      * Specifies whether the argument value must represent a
      * class that can be instantiated.
      *
-     * @param loadable whether the argument value must 
+     * @param instance whether the argument value must 
      * represent a class that can be instantiated.
      */
     public void setInstance(boolean instance) {

src/java/org/apache/commons/cli2/validation/DateValidator.java

@@ -22,7 +22,8 @@
 import java.util.ListIterator;
 
 /**
- * A Validator for date and time value(s).
+ * The <code>DateValidator</code> validates the argument values
+ * are date or time value(s).
  *
  * The following example shows how to validate that
  * an argument value(s) is a Date of the following 

src/java/org/apache/commons/cli2/validation/EnumValidator.java

@@ -20,7 +20,8 @@
 import java.util.Set;
 
 /**
- * A Validator for a list of known string values.
+ * The <code>EnumValidator</code> validates the string argument
+ * values are valid.
  *
  * The following example shows how to limit the valid values
  * for the color argument to 'red', 'green', or 'blue'.

src/java/org/apache/commons/cli2/validation/FileValidator.java

@@ -170,7 +170,7 @@ public boolean isExisting() {
      * Specifies whether the argument values must represent existing 
      * files/directories.
      *
-     * @param directory specifies whether the argument values must 
+     * @param existing specifies whether the argument values must 
      * represent existing files/directories.
      */
     public void setExisting(boolean existing) {
@@ -211,7 +211,7 @@ public boolean isHidden() {
      * Specifies whether the argument values must represent hidden 
      * files/directories.
      *
-     * @param file specifies whether the argument values must 
+     * @param hidden specifies whether the argument values must 
      * represent hidden files/directories.
      */
     public void setHidden(boolean hidden) {
@@ -233,7 +233,7 @@ public boolean isReadable() {
      * Specifies whether the argument values must represent readable 
      * files/directories.
      *
-     * @param file specifies whether the argument values must 
+     * @param readable specifies whether the argument values must 
      * represent readable files/directories.
      */
     public void setReadable(boolean readable) {
@@ -255,7 +255,7 @@ public boolean isWritable() {
      * Specifies whether the argument values must represent writable 
      * files/directories.
      *
-     * @param file specifies whether the argument values must 
+     * @param writable specifies whether the argument values must 
      * represent writable files/directories.
      */
     public void setWritable(boolean writable) {

src/java/org/apache/commons/cli2/validation/NumberValidator.java

@@ -84,7 +84,7 @@ public static NumberValidator getPercentInstance() {
     /**
      * Returns a <code>NumberValidator</code> for a general-purpose 
      * number format for the current default locale.
-     * @returns a <code>NumberValidator</code> for a general-purpose 
+     * @return a <code>NumberValidator</code> for a general-purpose 
      * number format for the current default locale.
      */
     public static NumberValidator getNumberInstance() {

src/java/org/apache/commons/cli2/validation/UrlValidator.java

@@ -28,7 +28,7 @@
  *
  * URLs can also be validated based on their scheme by using 
  * the {@link #setProtocol setProtocol} method, or by using the specified
- * {@link UrlValidator(java.lang.String) constructor}.
+ * {@link #UrlValidator(java.lang.String) constructor}.
  *
  * The following example shows how to limit the valid values
  * for the site argument to 'https' URLs.
@@ -65,7 +65,7 @@ public UrlValidator(final String protocol) {
     /**
      * Validate the list of values against the list of permitted values.
      * If a value is valid, replace the string in the <code>values</code>
-     * {@link java.util.List} with the {@link java.net.URL} instance.
+     * {@link java.util.List} with the { java.net.URL} instance.
      * 
      * @see org.apache.commons.cli2.validation.Validator#validate(java.util.List)
      */

src/java/org/apache/commons/cli2/validation/package.html

@@ -1,12 +1,16 @@
+<html>
+<body>
 Provides classes and interfaces for validating argument values.
 
 These classes are capable of validating argument values of the following type:
 
 <ul>
-  <li>file/directory</li>
-  <li>number</li>
-  <li>date/time</li>
-  <li>URL</li>
-  <li>enumeration</li>
-  <li>class</li>
+    <li>file/directory</li>
+    <li>number</li>
+    <li>date/time</li>
+    <li>URL</li>
+    <li>enumeration</li>
+    <li>class</li>
 </ul>
+</body>
+</html>