- javadoc updated

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

Author: John Keyes

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

@@ -1,5 +1,5 @@
-/**
- * Copyright 2003-2004 The Apache Software Foundation
+/*
+ * Copyright 2003-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.
@@ -16,7 +16,10 @@
 package org.apache.commons.cli2.validation;
 
 /**
- * An exception indicating validation failure
+ * An exception indicating validation failure.
+ *
+ * @author Rob Oxspring
+ * @author John Keyes
  */
 public class InvalidArgumentException extends Exception {
 

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

@@ -1,5 +1,5 @@
-/**
- * Copyright 2003-2004 The Apache Software Foundation
+/*
+ * Copyright 2003-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.
@@ -21,19 +21,49 @@
 import java.util.ListIterator;
 
 /**
- * A Validator instance that parses Numbers
+ * The <code>NumberValidator</code> validates the string argument
+ * values are numbers.  If the value is a number, the string value in
+ * the {@link java.util.List} of values is replaced with the
+ * {@link java.lang.Number} instance.
+ *
+ * A maximum and minimum value can also be specified using 
+ * the {@link #setMaximum setMaximum}, and the 
+ * {@link #setMinimum setMinimum} methods.
+ *
+ * The following example shows how to limit the valid values
+ * for the age attribute to integers less than 100.
+ *
+ * <pre>
+ * ...
+ * ArgumentBuilder builder = new ArgumentBuilder();
+ * NumberValidator validator = NumberValidator.getIntegerInstance();
+ * validator.setMaximum(new Integer(100));
+ * 
+ * Argument age = 
+ *     builder.withName("age");
+ *            .withValidator(validator);
+ * </pre>
+ * 
+ * @author Rob Oxspring
+ * @author John Keyes
  */
 public class NumberValidator implements Validator {
 
     /**
-     * @return an instance using local currency format
+     * Returns a <code>NumberValidator</code> for a currency format 
+     * for the current default locale.
+     * @return a <code>NumberValidator</code> for a currency format 
+     * for the current default locale.
      */
     public static NumberValidator getCurrencyInstance() {
         return new NumberValidator(NumberFormat.getCurrencyInstance());
     }
 
     /**
-     * @return an instance using local integer format
+     * Returns a <code>NumberValidator</code> for an integer number format 
+     * for the current default locale.
+     * @return a <code>NumberValidator</code> for an integer number format 
+     * for the current default locale.
      */
     public static NumberValidator getIntegerInstance() {
         final NumberFormat format = NumberFormat.getNumberInstance();
@@ -42,25 +72,36 @@ public static NumberValidator getIntegerInstance() {
     }
 
     /**
-     * @return an instance using local percent format
+     * Returns a <code>NumberValidator</code> for a percentage format 
+     * for the current default locale.
+     * @return a <code>NumberValidator</code> for a percentage format 
+     * for the current default locale.
      */
     public static NumberValidator getPercentInstance() {
         return new NumberValidator(NumberFormat.getPercentInstance());
     }
 
     /**
-     * @return an instance using local number format
+     * 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 
+     * number format for the current default locale.
      */
     public static NumberValidator getNumberInstance() {
         return new NumberValidator(NumberFormat.getNumberInstance());
     }
 
+    /** the <code>NumberFormat</code> being used. */
     private NumberFormat format;
+
+    /** the lower bound for argument values. */
     private Number minimum = null;
+    
+    /** the upper bound for argument values */
     private Number maximum = null;
 
     /**
-     * Creates a new NumberValidator
+     * Creates a new NumberValidator.
      */
     public NumberValidator() {
         this(NumberFormat.getInstance());
@@ -74,6 +115,13 @@ public NumberValidator(final NumberFormat format) {
         this.format = format;
     }
 
+    /**
+     * 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.lang.Number} instance.
+     * 
+     * @see org.apache.commons.cli2.validation.Validator#validate(java.util.List)
+     */
     public void validate(final List values) throws InvalidArgumentException {
         for (final ListIterator i = values.listIterator(); i.hasNext();) {
             final String value = (String)i.next();
@@ -96,44 +144,56 @@ public void validate(final List values) throws InvalidArgumentException {
     }
 
     /**
-     * @return the format of a valid Number
+     * Return the format being used to validate argument values against.
+     *
+     * @return the format being used to validate argument values against.
      */
     public NumberFormat getFormat() {
         return format;
     }
 
     /**
-     * @return the maximum value for a valid Number
+     * Specify the format being used to validate argument values against.
+     *
+     * @param format the format being used to validate argument values against.
+     */
+    public void setFormat(NumberFormat format) {
+        this.format = format;
+    }
+    
+    /**
+     * Return the maximum value allowed for an argument value.
+     *
+     * @return the maximum value allowed for an argument value.
      */
     public Number getMaximum() {
         return maximum;
     }
 
     /**
-     * @param maximum the maximum value for a valid Number
+     * Specify the maximum value allowed for an argument value.
+     *
+     * @param maximum the maximum value allowed for an argument value.
      */
     public void setMaximum(Number maximum) {
         this.maximum = maximum;
     }
 
     /**
-     * @return the minimum value for a valid Number
+     * Return the minimum value allowed for an argument value.
+     *
+     * @return the minimum value allowed for an argument value.
      */
     public Number getMinimum() {
         return minimum;
     }
 
     /**
-     * @param minimum the minimum value for a valid Number
+     * Specify the minimum value allowed for an argument value.
+     *
+     * @param minimum the minimum value allowed for an argument value.
      */
     public void setMinimum(Number minimum) {
         this.minimum = minimum;
     }
-
-    /**
-     * @param format The format to set.
-     */
-    public void setFormat(NumberFormat format) {
-        this.format = format;
-    }
 }

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

@@ -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}.
+     * {@link java.util.List} with the {@link java.net.URL} instance.
      * 
      * @see org.apache.commons.cli2.validation.Validator#validate(java.util.List)
      */