fixed combined switch stuff and added doxygen comments

include/tclap/Arg.h

@@ -44,11 +44,18 @@ class Arg
 {
 	private: 
 
+		/**
+		 * Indicates whether the rest of the arguments should be ignored.
+		 */
 		static bool _ignoreRest;
 
 
 	protected:
 
+		/**
+		 * The delimiter that separates an argument flag/name from the
+		 * value.
+		 */
 		static char _delimiter; 
 
 		/** 
@@ -114,16 +121,54 @@ class Arg
 
 	public:
 		
+		/**
+		 * Begin ignoring arguments since the "--" argument was specified.
+		 */
 		static void beginIgnoring() { Arg::_ignoreRest = true; }
+		
+		/**
+		 * Whether to ignore the rest.
+		 */
 		static bool ignoreRest() { return Arg::_ignoreRest; }
 		
+		/**
+		 * The char used as a place holder when SwitchArgs are combined.
+		 * Currently set to '*', which shouldn't cause many problems since
+		 * *'s are expanded by most shells on the command line.  
+		 */
+		static const char blankChar; 
+		
+		/**
+		 * The char that indicates the beginning of a flag.  Currently '-'.
+		 */
+		static const char flagStartChar; 
+		
+		/**
+		 * The sting that indicates the beginning of a flag.  Currently "-".
+		 * Should be identical to flagStartChar.
+		 */
+		static const string flagStartString;
+		
+		/**
+		 * The sting that indicates the beginning of a name.  Currently "--".
+		 * Should be flagStartChar twice.
+		 */
+		static const string nameStartString;
+
 		/**
 		 * Sets the delimiter for all arguments.
+		 * \param c - The character that delimits flags/names from values.
 		 */
 		static void setDelimiter( char c ) { Arg::_delimiter = c; }
 
 		/**
 		 * Primary constructor.
+		 * \param flag - The flag identifying the argument.
+		 * \param name - The name identifying the argument.
+		 * \param desc - The description of the argument, used in the usage.
+		 * \param req - Whether the argument is required.
+		 * \param valreq - Whether the a value is required for the argument.
+		 * \param v - The visitor checked by the argument. Defaults to NULL.
 		 */
 		Arg(const string& flag, 
 			const string& name, 
@@ -140,14 +185,16 @@ class Arg
 
 		/**
 		 * Copy constructor.
+		 * \param a - The Arg to be copied. 
 		 */
-		Arg(const Arg&);
+		Arg(const Arg& a);
 
 		/**
 		 * Operator =.
 		 * Assignment operator.
+		 * \param a - The Arg to be assigned to this.
 		 */
-		Arg& operator=(const Arg&);
+		Arg& operator=(const Arg& a);
 
 		/**
 		 * Destructor.
@@ -171,8 +218,9 @@ class Arg
 		/**
 		 * Operator ==.
 		 * Equality operator. Must be virtual to handle unlabeled args.
+		 * \param a - The Arg to be compared to this.
 		 */
-		virtual bool operator==(const Arg&);
+		virtual bool operator==(const Arg& a);
 
 		/**
 		 * Returns the argument flag.
@@ -214,6 +262,8 @@ class Arg
 		 * This is generally called by the processArg() method.  This
 		 * method could be re-implemented by a child to change how 
 		 * arguments are specified on the command line.
+		 * \param s - The string to be compared to the flag/name to determine
+		 * whether the arg matches.
 		 */
 		virtual bool argMatches( const string& s ) const;
 
@@ -225,19 +275,32 @@ class Arg
 
 		/**
 		 * Returns a short ID for the usage.
+		 * \param valueId - The value used in the id.
 		 */
 		virtual string shortID( const string& valueId = "val" ) const;
 
 		/**
 		 * Returns a long ID for the usage.
+		 * \param valueId - The value used in the id.
 		 */
 		virtual string longID( const string& valueId = "val" ) const;
 
 		/**
 		 * Trims a value off of the flag.
+		 * \param flag - The string from which the flag and value will be 
+		 * trimmed. Contains the flag once the value has been trimmed. 
+		 * \param value - Where the value trimmed from the string will
+		 * be stored.
 		 */
 		virtual void trimFlag( string& flag, string& value ) const;
 
+		/**
+		 * Checks whether a given string has blank chars, indicating that
+		 * it is a combined SwitchArg.  If so, return true, otherwise return
+		 * false.
+		 */
+		bool _hasBlanks( const string& s ) const;
+
 
 };
 

include/tclap/ArgException.h

@@ -29,20 +29,42 @@ using namespace std;
 
 namespace TCLAP {
 
+/**
+ * A simple class that defines and argument exception.  Should be caught
+ * whenever a CmdLine is created and parsed.
+ */
 class ArgException
 {
 	public:
 	
+		/**
+		 * Constructor.
+		 * \param text - The text of the exception.
+		 * \param id - The text identifying the argument source 
+		 * of the exception.
+		 */
 		ArgException( const string& text = "undefined exception", 
 					  const string& id = "undefined" )
 			: _errorText(text), _argId( id ) {}; 
 		
+		/**
+		 * Copy constructor.
+		 * \param e - The ArgException that will be copied.
+		 */
 		ArgException(const ArgException& e) 
 			: _errorText(e._errorText), _argId(e._argId) {};
 
+		/**
+		 * Destructor.
+		 */
 		~ArgException() {};
 
 	
+		/**
+		 * Assignment operator.
+		 * \param e - The ArgException that will be assigned
+		 * to this.
+		 */
 		ArgException& operator=( const ArgException& e )
 		{ 
 			if ( this != &e ) 
@@ -53,7 +75,14 @@ class ArgException
 			return *this; 
 		};
 
+		/**
+		 * Returns the error text.
+		 */
 		string error() { return ( _errorText ); };
+
+		/**
+		 * Returns the argument id.
+		 */
 		string argId() 
 		{ 
 			if ( _argId == "undefined" )
@@ -64,7 +93,14 @@ class ArgException
 
 	private:
 
+		/**
+		 * The text of the exception message.
+		 */
 		string _errorText;
+
+		/**
+		 * The argument related to this exception.
+		 */
 		string _argId;
 
 };

include/tclap/CmdLine.h

@@ -45,22 +45,88 @@ namespace TCLAP {
 class CmdLine
 {
 	protected:
+
+		/**
+		 * The list of arguments that will be tested against the
+		 * command line.
+		 */
 		list<Arg*> _argList;
+
+		/**
+		 * The name of the program.  Set to argv[0].
+		 */
 		string _progName;
+
+		/**
+		 * A message used to describe the program.  Used in the usage output.
+		 */
 		string _message;
+
+		/**
+		 * The version to be displayed with the --version switch.
+		 */
 		string _version;
-		int _maxLength;
+
+		/**
+		 * The number of arguments that are required to be present on 
+		 * the command line. This is set dynamically, based on the 
+		 * Args added to the CmdLine object.
+		 */
 		int _numRequired;
+
+		/**
+		 * The character that is used to separate the argument flag/name 
+		 * from the value.  Defaults to ' ' (space).
+		 */
 		char _delimiter;
 
+		/**
+		 * Checks whether a name/flag string matches entirely matches
+		 * the Arg::blankChar.  Used when multiple switches are combined
+		 * into a single argument.
+		 * \param s - The message to be used in the usage.
+		 */
+		bool _emptyCombined(const string& s);
+
 	public:
+
+		/**
+		 * Command line constructor. Defines how the arguments will be
+		 * parsed.
+		 * \param message - The message to be used in the usage
+		 * output.
+		 * \param delimiter - The character that is used to separate
+		 * the argument flag/name from the value.  Defaults to ' ' (space).
+		 * \param version - The version number to be used in the
+		 * --version switch.
+		 */
 		CmdLine(const string& message, 
 				const char delimiter = ' ',
 				const string& version = "none" );
 
+		/**
+		 * Adds an argument to the list of arguments to be parsed.
+		 * \param a - Argument to be added. 
+		 */
 		void add( Arg& a );
+
+		/**
+		 * Prints the usage to stdout and exits.
+		 * \param exitVal - Value to exit with. 
+		 */
 		void usage( int exitVal = 0 );
+
+		/**
+		 * Prints the version to stdout and exits.
+		 * \param exitVal - Value to exit with. 
+		 */
 		void version( int exitVal = 0 );
+
+		/**
+		 * Parses the command line.
+		 * \param argc - Number of arguments.
+		 * \param argv - Array of arguments.
+		 */
 		void parse(int argc, char** argv);
 };
 

include/tclap/HelpVisitor.h

@@ -26,14 +26,29 @@
 
 namespace TCLAP {
 
+/**
+ * A Visitor object that calls the usage method of a given CmdLine.
+ */
 class HelpVisitor: public Visitor
 {
 	protected:
+
+		/**
+		 * The CmdLine that will be called for the usage method.
+		 */
 		CmdLine* _cmd;
 
 	public:
+
+		/**
+		 * Constructor.
+		 * \param cmd - The CmdLine that will called for usage method.
+		 */
 		HelpVisitor(CmdLine* cmd) : Visitor(), _cmd( cmd ) {};
 
+		/**
+		 * Calls the usage method of the CmdLine.
+		 */
 		void visit() { _cmd->usage(0); }
 		
 };

include/tclap/IgnoreRestVisitor.h

@@ -28,11 +28,22 @@
 
 namespace TCLAP {
 
+/**
+ * A Vistor that tells the CmdLine to begin ignoring arguments after
+ * this one is parsed.
+ */
 class IgnoreRestVisitor: public Visitor
 {
 	public:
+
+		/**
+		 * Constructor.
+		 */
 		IgnoreRestVisitor() : Visitor() {};
 
+		/**
+		 * Sets Arg::_ignoreRest.
+		 */
 		void visit() { Arg::beginIgnoring();  }
 };
 

include/tclap/MultiArg.h

@@ -32,19 +32,53 @@ using namespace std;
 
 namespace TCLAP {
 
+/**
+ * An argument that allows multiple values of type T to be specified.  Very
+ * similar to a ValueArg, except a vector of values will be returned
+ * instead of just one.
+ */
 template<class T>
 class MultiArg : public Arg
 {
 	protected:
 
+		/**
+		 * The list of values parsed from the CmdLine.
+		 */
 		vector<T> _values;
 
+		/**
+		 * The description of type T to be used in the usage.
+		 */
 		string _typeDesc;
 
+		/**
+		 * Extracts the value from the string.
+		 * Attempts to parse string as type T, if this fails an exception
+		 * is thrown.
+		 * \param val - The string to be read.
+		 */
 		void _extractValue( const string& val ); 
   
 	public:
 
+		/**
+		 * Constructor.
+		 * \param flag - The one character flag that identifies this
+		 * argument on the command line.
+		 * \param name - A one word name for the argument.  Can be
+		 * used as a long flag on the command line.
+		 * \param desc - A description of what the argument is for or
+		 * does.
+		 * \param req - Whether the argument is required on the command
+		 * line.
+		 * \param typeDesc - A short, human readable description of the
+		 * type that this object expects.  This is used in the generation
+		 * of the USAGE statement.  The goal is to be helpful to the end user
+		 * of the program.
+		 * \param v - An optional visitor.  You probably should not
+		 * use this unless you have a very good reason.
+		 */
 		MultiArg( const string& flag,
 				  const string& name,
 				  const string& desc,
@@ -52,18 +86,44 @@ class MultiArg : public Arg
 				  const string& typeDesc,
 				  Visitor* v = NULL);
 
+		/**
+		 * Destructor.
+		 */
 		~MultiArg();
 
+		/**
+		 * Handles the processing of the argument.
+		 * This re-implements the Arg version of this method to set the
+		 * _value of the argument appropriately.  It knows the difference
+		 * between labeled and unlabeled.
+		 * \param i - Pointer the the current argument in the list.
+		 * \param args - Mutable list of strings. Passed from main().
+		 */
 		virtual bool processArg(int* i, vector<string>& args); 
 
+		/**
+		 * Returns a vector of type T containing the values parsed from
+		 * the command line.
+		 */
 		const vector<T>& getValue() ;
 
+		/**
+		 * Returns the a short id string.  Used in the usage. 
+		 * \param val - value to be used.
+		 */
 		virtual string shortID(const string& val="val") const;
+
+		/**
+		 * Returns the a long id string.  Used in the usage. 
+		 * \param val - value to be used.
+		 */
 		virtual string longID(const string& val="val") const;
 
 };
 
-
+/**
+ *
+ */
 template<class T>
 MultiArg<T>::MultiArg(const string& flag, 
 				      const string& name,
@@ -75,18 +135,30 @@ MultiArg<T>::MultiArg(const string& flag,
   _typeDesc( typeDesc )
 { };
 
+/**
+ *
+ */
 template<class T>
 MultiArg<T>::~MultiArg() { };
 
+/**
+ *
+ */
 template<class T>
 const vector<T>& MultiArg<T>::getValue() { return _values; };
 
+/**
+ *
+ */
 template<class T>
 bool MultiArg<T>::processArg(int *i, vector<string>& args) 
 {
 	if ( _ignoreable && Arg::ignoreRest() )
 		return false;
 
+	if ( _hasBlanks( args[*i] ) )
+		return false;
+
 	string flag = args[*i];
 	string value = "";
 
@@ -116,6 +188,9 @@ bool MultiArg<T>::processArg(int *i, vector<string>& args)
 		return false;
 }
 
+/**
+ *
+ */
 template<class T>
 void MultiArg<T>::_extractValue( const string& val )
 {
@@ -130,6 +205,9 @@ void MultiArg<T>::_extractValue( const string& val )
 	_checkWithVisitor();
 }
 
+/**
+ *
+ */
 template<class T>
 string MultiArg<T>::shortID(const string& val) const
 {
@@ -138,6 +216,9 @@ string MultiArg<T>::shortID(const string& val) const
 	return id;
 }
 
+/**
+ *
+ */
 template<class T>
 string MultiArg<T>::longID(const string& val) const
 {

include/tclap/SwitchArg.h

@@ -33,31 +33,68 @@ using namespace std;
 
 namespace TCLAP {
 
+/**
+ * A simple switch argument.  If the switch is set on the command line, then
+ * the getValue method will return the opposite of the default value for the
+ * switch.
+ */
 class SwitchArg : public Arg
 {
 	protected:
 
+		/**
+		 * The value of the switch.
+		 */
 		bool _value;
 
 
 	public:
 
+        /**
+		 * SwitchArg constructor.
+		 * \param flag - The one character flag that identifies this
+		 * argument on the command line.
+		 * \param name - A one word name for the argument.  Can be
+		 * used as a long flag on the command line.
+		 * \param desc - A description of what the argument is for or
+		 * does.
+		 * \param def - The default value for this Switch. 
+		 * \param v - An optional visitor.  You probably should not
+		 * use this unless you have a very good reason.
+		 */
 		SwitchArg(const string& flag, 
 			      const string& name, 
 			      const string& desc,
-			      bool _default,
+			      bool def,
 				  Visitor* v = NULL);
 
+		/**
+		 * Destructor.
+		 */
 		~SwitchArg();
 
+        /**
+		 * Handles the processing of the argument.
+		 * This re-implements the Arg version of this method to set the
+		 * _value of the argument appropriately.
+		 * \param i - Pointer the the current argument in the list.
+		 * \param args - Mutable list of strings. Passed
+		 * in from main().
+		 */
 		virtual bool processArg(int* i, vector<string>& args); 
 
+		/**
+		 * Checks a string to see if any of the chars in the string
+		 * match the flag for this Switch.
+		 */
 		bool combinedSwitchesMatch(string& combined);
 
+		/**
+		 * Returns bool, whether or not the switch has been set.
+		 */
 		bool getValue() ;
 };
 
-
 }
 
 #endif

include/tclap/UnlabeledMultiArg.h

@@ -32,21 +32,63 @@ using namespace std;
 
 namespace TCLAP {
 
+/**
+ * Just like a MultiArg, except that the arguments are unlabeled.  Basically,
+ * this Arg will slurp up everything that hasn't been matched to another 
+ * Arg.
+ */
 template<class T>
 class UnlabeledMultiArg : public MultiArg<T>
 {
 	public:
 		
+		/**
+		 * Constructor.  
+		 * \param name - The name of the Arg. Note that this is used for
+		 * identification, not as a long flag.
+		 * \param desc - A description of what the argument is for or
+		 * does.
+		 * \param typeDesc - A short, human readable description of the
+		 * type that this object expects.  This is used in the generation
+		 * of the USAGE statement.  The goal is to be helpful to the end user
+		 * of the program.
+		 * \param ignoreable - Whether or not this argument can be ignored
+		 * using the "--" flag.
+		 * \param v - An optional visitor.  You probably should not
+		 * use this unless you have a very good reason.
+		 */
 		UnlabeledMultiArg( const string& name,
 				           const string& desc,
 				           const string& typeDesc,
 						   bool ignoreable = false,
 				           Visitor* v = NULL );
 
+		/**
+		 * Handles the processing of the argument.
+		 * This re-implements the Arg version of this method to set the
+		 * _value of the argument appropriately.  It knows the difference
+		 * between labeled and unlabeled.
+		 * \param i - Pointer the the current argument in the list.
+		 * \param args - Mutable list of strings. Passed from main().
+		 */
 		virtual bool processArg(int* i, vector<string>& args); 
 
+		/**
+		 * Returns the a short id string.  Used in the usage.
+		 * \param val - value to be used.
+		 */
 		virtual string shortID(const string& val="val") const;
+
+		/**
+		 * Returns the a long id string.  Used in the usage.
+		 * \param val - value to be used.
+		 */
 		virtual string longID(const string& val="val") const;
+
+		/**
+		 * Opertor ==.
+		 * \param a - The Arg to be compared to this.
+		 */
 		virtual bool operator==(const Arg& a) const;
 
 };
@@ -65,6 +107,10 @@ UnlabeledMultiArg<T>::UnlabeledMultiArg(const string& name,
 template<class T>
 bool UnlabeledMultiArg<T>::processArg(int *i, vector<string>& args) 
 {
+
+	if ( _hasBlanks( args[*i] ) )
+		return false;
+
 	// never ignore an unlabeled multi arg
 
 	_extractValue( args[*i] );

include/tclap/UnlabeledValueArg.h

@@ -123,11 +123,15 @@ UnlabeledValueArg<T>::UnlabeledValueArg(const string& name,
 template<class T>
 bool UnlabeledValueArg<T>::processArg(int *i, vector<string>& args) 
 {
-	// never ignore an unlabeled arg
 	
 	if ( _alreadySet )
 		return false;
 	
+	if ( _hasBlanks( args[*i] ) )
+		return false;
+
+	// never ignore an unlabeled arg
+	
 	_extractValue( args[*i] );
 	_alreadySet = true;
 	return true;

include/tclap/ValueArg.h

@@ -66,7 +66,7 @@ class ValueArg : public Arg
 		 * Extracts the value from the string.
 		 * Attempts to parse string as type T, if this fails an exception
 		 * is thrown.
-		 * \param val - string value to be parsed. 
+		 * \param val - value to be parsed. 
 		 */
 		void _extractValue( const string& val ); 
 
@@ -126,11 +126,13 @@ class ValueArg : public Arg
 
 		/**
 		 * Specialization of shortID.
+		 * \param val - value to be used.
 		 */
 		virtual string shortID(const string& val = "val") const;
 
 		/**
 		 * Specialization of longID.
+		 * \param val - value to be used.
 		 */
 		virtual string longID(const string& val = "val") const;
 
@@ -175,8 +177,10 @@ bool ValueArg<T>::processArg(int *i, vector<string>& args)
 	if ( _ignoreable && Arg::ignoreRest() )
 		return false;
 
-	string flag = args[*i];
+	if ( _hasBlanks( args[*i] ) )
+		return false;
 
+	string flag = args[*i];
 	string value = "";
 	trimFlag( flag, value );
 

include/tclap/VersionVisitor.h

@@ -27,14 +27,30 @@
 
 namespace TCLAP {
 
+/**
+ * A Vistor that will call the version method of the given CmdLine and
+ * then exit.
+ */
 class VersionVisitor: public Visitor
 {
 	protected:
+
+		/**
+		 * The CmdLine of interest.
+		 */
 		CmdLine* _cmd;
 		
 	public:
+
+		/**
+		 * Constructor.
+		 * \param cmd - The CmdLine whose version method will be called.
+		 */
 		VersionVisitor(CmdLine* cmd) : Visitor(), _cmd( cmd ) {};
 
+		/**
+		 * Prints the version to stdout.
+		 */
 		void visit() { _cmd->version(0); }
 };
 

include/tclap/Visitor.h

@@ -25,10 +25,21 @@
 
 namespace TCLAP {
 
+/**
+ * A base class that defines the interface for visitors.
+ */
 class Visitor
 {
 	public:
+
+		/**
+		 * Constructor. Does nothing.
+		 */
 		Visitor() {};
+
+		/**
+		 * Does nothing. Should be overridden by child.
+		 */
 		virtual void visit() {};
 };