javadoc updates

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

Author: John Keyes

src/java/org/apache/commons/cli/AlreadySelectedException.java

@@ -58,20 +58,22 @@
  * <http://www.apache.org/>.
  *
  */
-
 package org.apache.commons.cli;
 
-/** <p>Exception thrown when more than one option in an option group
+/** 
+ * <p>Thrown when more than one option in an option group
  * has been provided.</p>
  *
- * @author John Keyes (john @ integralsource.com)
- * @version $Revision: 1.4 $
+ * @author John Keyes ( jbjk at mac.com )
+ * @see ParseException
  */
 public class AlreadySelectedException extends ParseException {
 
-    /** Construct a new Exception with a message
+    /** 
+     * <p>Construct a new <code>AlreadySelectedException</code> 
+     * with the specified detail message.</p>
      *
-     * @param message Explanation of the exception
+     * @param message the detail message
      */
     public AlreadySelectedException( String message ) {
         super( message );

src/java/org/apache/commons/cli/BasicParser.java

@@ -1,14 +1,92 @@
+/*
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//cli/src/java/org/apache/commons/cli/BasicParser.java,v 1.2 2002/08/26 20:15:02 jkeyes Exp $
+ * $Revision: 1.2 $
+ * $Date: 2002/08/26 20:15:02 $
+ *
+ * ====================================================================
+ *
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 1999-2001 The Apache Software Foundation.  All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ *    any, must include the following acknowlegement:
+ *       "This product includes software developed by the
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowlegement may appear in the software itself,
+ *    if and wherever such third-party acknowlegements normally appear.
+ *
+ * 4. The names "The Jakarta Project", "Commons", and "Apache Software
+ *    Foundation" must not be used to endorse or promote products derived
+ *    from this software without prior written permission. For written
+ *    permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ *    nor may "Apache" appear in their names without prior written
+ *    permission of the Apache Group.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
 package org.apache.commons.cli;
 
 /**
+ * The class BasicParser provides a very simple implementation of
+ * the {@link Parser#flatten(Options,String[],boolean) flatten} method.
+ *
  * @author John Keyes (jbjk at mac.com)
+ * @see Parser
  */
 public class BasicParser extends Parser {
 
+    /**
+     * <p>A simple implementation of {@link Parser}'s abstract
+     * {@link Parser#flatten(Options,String[],boolean) flatten} method.</p>
+     *
+     * <p><b>Note:</b> <code>options</code> and <code>stopAtNonOption</code>
+     * are not used in this <code>flatten</code> method.</p>
+     *
+     * @param options The command line {@link Options}
+     * @param arguments The command line arguments to be parsed
+     * @param stopAtNonOption Specifies whether to stop flattening
+     * when an non option is found.
+     * @return The <code>arguments</code> String array.
+     */
     protected String[] flatten( Options options, 
                                 String[] arguments, 
                                 boolean stopAtNonOption )
     {
+        // just echo the arguments
         return arguments;
     }
 }

src/java/org/apache/commons/cli/CommandLine.java

@@ -58,7 +58,6 @@
  * <http://www.apache.org/>.
  *
  */
-
 package org.apache.commons.cli;
 
 import java.util.Collection;
@@ -68,7 +67,8 @@
 import java.util.LinkedList;
 import java.util.Map;
 
-/** <p>Represents list of arguments parsed against
+/** 
+ * <p>Represents list of arguments parsed against
  * a {@link Options} descriptor.<p>
  *
  * <p>It allows querying of a boolean {@link #hasOption(String opt)},
@@ -81,8 +81,6 @@
  * @author bob mcwhirter (bob @ werken.com)
  * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
  * @author John Keyes (jbjk at mac.com)
- *
- * @version $Revision: 1.4 $
  */
 public class CommandLine {
 
@@ -104,7 +102,8 @@ public class CommandLine {
     CommandLine() {
     }
 
-    /** <p>Query to see if an option has been set.</p>
+    /** 
+     * <p>Query to see if an option has been set.</p>
      *
      * @param opt Short name of the option
      * @return true if set, false if not
@@ -113,7 +112,8 @@ public boolean hasOption(String opt) {
         return options.containsKey( opt );
     }
 
-    /** <p>Query to see if an option has been set.</p>
+    /** 
+     * <p>Query to see if an option has been set.</p>
      *
      * @param opt character name of the option
      * @return true if set, false if not
@@ -123,8 +123,10 @@ public boolean hasOption( char opt ) {
     }
 
     /**
+     * <p>Return the <code>Object</code> type of this <code>Option</code>.</p>
+     *
      * @param opt the name of the option
-     * @return the type of opt
+     * @return the type of this <code>Option</code>
      */
     public Object getOptionObject( String opt ) {
         String res = getOptionValue( opt );
@@ -134,36 +136,44 @@ public Object getOptionObject( String opt ) {
     }
 
     /**
+     * <p>Return the <code>Object</code> type of this <code>Option</code>.</p>
+     *
      * @param opt the name of the option
      * @return the type of opt
      */
     public Object getOptionObject( char opt ) {
         return getOptionObject( String.valueOf( opt ) );
     }
 
-    /** <p>Retrieve the argument, if any,  of an option.</p>
+    /** 
+     * <p>Retrieve the argument, if any, of this option.</p>
      *
      * @param opt the name of the option
-     * @return Value of the argument if option is set, and has an argument, else null.
+     * @return Value of the argument if option is set, and has an argument,
+     * otherwise null.
      */
     public String getOptionValue( String opt ) {
         String[] values = getOptionValues(opt);
         return (values == null) ? null : values[0];
     }
 
-    /** <p>Retrieve the argument, if any,  of an option.</p>
+    /** 
+     * <p>Retrieve the argument, if any, of this option.</p>
      *
      * @param opt the character name of the option
-     * @return Value of the argument if option is set, and has an argument, else null.
+     * @return Value of the argument if option is set, and has an argument,
+     * otherwise null.
      */
     public String getOptionValue( char opt ) {
         return getOptionValue( String.valueOf( opt ) );
     }
 
-    /** <p>Retrieves the array of values, if any, of an option.</p>
+    /** 
+     * <p>Retrieves the array of values, if any, of an option.</p>
      *
      * @param opt string name of the option
-     * @return An array of values if the option is set, and has an argument, else null.
+     * @return Values of the argument if option is set, and has an argument,
+     * otherwise null.
      */
     public String[] getOptionValues( String opt ) {
         List values = new java.util.ArrayList();
@@ -180,49 +190,57 @@ public String[] getOptionValues( String opt ) {
         return (values.size() == 0) ? null : (String[])values.toArray(new String[]{});
     }
 
-    /** <p>Retrieves the array of values, if any, of an option.</p>
+    /** 
+     * <p>Retrieves the array of values, if any, of an option.</p>
      *
      * @param opt character name of the option
-     * @return An array of values if the option is set, and has an argument, else null.
+     * @return Values of the argument if option is set, and has an argument,
+     * otherwise null.
      */
     public String[] getOptionValues( char opt ) {
         return getOptionValues( String.valueOf( opt ) );
     }
 
-    /** <p>Retrieve the argument, if any, of an option.</p>
+    /** 
+     * <p>Retrieve the argument, if any, of an option.</p>
      *
      * @param opt name of the option
      * @param defaultValue is the default value to be returned if the option is not specified
-     * @return Value of the argument if option is set, and has an argument, else null.
+     * @return Value of the argument if option is set, and has an argument,
+     * otherwise <code>defaultValue</code>.
      */
     public String getOptionValue( String opt, String defaultValue ) {
         String answer = getOptionValue( opt );
         return ( answer != null ) ? answer : defaultValue;
     }
 
-    /** <p>Retrieve the argument, if any, of an option.</p>
+    /** 
+     * <p>Retrieve the argument, if any, of an option.</p>
      *
      * @param opt character name of the option
      * @param defaultValue is the default value to be returned if the option is not specified
-     * @return Value of the argument if option is set, and has an argument, else null.
+     * @return Value of the argument if option is set, and has an argument,
+     * otherwise <code>defaultValue</code>.
      */
     public String getOptionValue( char opt, String defaultValue ) {
         return getOptionValue( String.valueOf( opt ), defaultValue );
     }
 
-    /** <p>Retrieve any left-over non-recognized options and arguments</p>
+    /** 
+     * <p>Retrieve any left-over non-recognized options and arguments</p>
      *
-     * @return an array of remaining items passed in but not parsed
+     * @return remaining items passed in but not parsed as an array
      */
     public String[] getArgs() {
         String[] answer = new String[ args.size() ];
         args.toArray( answer );
         return answer;
     }
 
-    /** <p>Retrieve any left-over non-recognized options and arguments</p>
+    /** 
+     * <p>Retrieve any left-over non-recognized options and arguments</p>
      *
-     * @return List of remaining items passed in but not parsed
+     * @return remaining items passed in but not parsed as a <code>List</code>.
      */
     public List getArgList() {
         return args;

src/java/org/apache/commons/cli/CommandLineParser.java

@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//cli/src/java/org/apache/commons/cli/CommandLineParser.java,v 1.2 2002/07/04 22:32:12 jkeyes Exp $
- * $Revision: 1.2 $
- * $Date: 2002/07/04 22:32:12 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//cli/src/java/org/apache/commons/cli/CommandLineParser.java,v 1.3 2002/08/26 20:15:02 jkeyes Exp $
+ * $Revision: 1.3 $
+ * $Date: 2002/08/26 20:15:02 $
  *
  * ====================================================================
  *
@@ -61,6 +61,10 @@
 package org.apache.commons.cli;
 
 /**
+ * A class that implements the <code>CommandLineParser</code> interface 
+ * can parse a String array according to the {@link Options} specified
+ * and return a {@link CommandLine}.
+ *
  * @author John Keyes (jbjk at mac.com)
  */
 public interface CommandLineParser {

src/java/org/apache/commons/cli/CommandLineParserFactory.java

@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//cli/src/java/org/apache/commons/cli/Attic/CommandLineParserFactory.java,v 1.3 2002/08/24 22:15:31 jkeyes Exp $
- * $Revision: 1.3 $
- * $Date: 2002/08/24 22:15:31 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//cli/src/java/org/apache/commons/cli/Attic/CommandLineParserFactory.java,v 1.4 2002/08/26 20:15:02 jkeyes Exp $
+ * $Revision: 1.4 $
+ * $Date: 2002/08/26 20:15:02 $
  *
  * ====================================================================
  *
@@ -73,13 +73,15 @@ public class CommandLineParserFactory {
     private static String DEFAULT_PARSER = "org.apache.commons.cli.PosixParser";
 
     /**
-     * @return the CommandLineParser
+     * @return the default CommandLineParser
      */
     public static CommandLineParser newParser() {
         return newParser( DEFAULT_PARSER );
     }
 
     /**
+     * @param classname the name of the parser class
+     * 
      * @return the CommandLineParser specified by <code>classname</code>.
      */
     public static CommandLineParser newParser( String classname ) {