added documentation to arguments.h

David Mayerich
1 parent 1cb3eb53
Showing 3 changed files with 81 additions and 11 deletions Show diff stats
.gitignore
.gitmodules
stim/parser/arguments.h
-html/*
-latex/*
 \ No newline at end of file
+stim/html/*
+stim/latex/*
 \ No newline at end of file
-[submodule "stim"]
-	path = stim
-	url = https://github.com/dmayerich/stim.git
@@ -237,6 +237,48 @@ namespace stim{
 		unsigned int index;
 	};
+    /**The arglist class implements command line arguments.
+        Example:
+    
+        1) Create an arglist instance:
+            
+            stim::arglist args;
+
+        2) Test to see if ANSI output is supported (arguments will use color if it is). Generally, Windows consoles don't support ANSI.
+
+            #ifdef _WIN32
+                args.set_ansi(false);
+            #endif
+
+        3) Add arguments:
+
+            args.add("help", "prints this help");
+            args.add("foo", "foo takes a single integer value", "", "[intval]");
+            args.add("bar", "bar takes two floating point values", "", "[value1], [value2]");
+
+        4) You generally want to immediately test for help and output available arguments:
+
+            if(args["help"].is_set())
+                std::cout<<args.str();
+
+        5) Parse the command line:
+
+            args.parse(argc, argv);
+
+        6)  Retrieve values:
+
+            int foo;
+            float bar1, bar2;
+            if(args["foo"])
+                foo = args["foo"].as_int();
+            if(args["bar"]){
+                bar1 = args["bar"].as_float(0);
+                bar2 = args["bar"].as_float(1);
+            }
+
+
+    **/
+
 	class arglist
 	{
     private:
@@ -259,6 +301,9 @@ namespace stim{
         	ansi = true;
         }
+        ///Sets ANSI support (default is on), which allows colored values in the help output.
+
+        /// @param b is a boolean value specifying ANSI support (true is on, false is off)
 		void set_ansi(bool b)
 		{
 			ansi = b;
@@ -266,6 +311,12 @@ namespace stim{
 				opts[i].set_ansi(ansi);
 		}
+        ///Add a supported command line argument.
+
+        /// @param _name is the name of the command line argument (supplied as --name)
+        /// @param _desc is a text description of the argument
+        /// @param _default is the default value of the argument
+        /// @param _range is the supported range of values, list of values, etc. It will be displayed to the user.
         void add(std::string _name, std::string _desc, std::string _default = "", std::string _range = "")
         {
             cmd_option opt(_name, _desc, _default, _range);
@@ -275,6 +326,9 @@ namespace stim{
             col_width = std::max<int>(col_width, opt.col_width());
         }
+        ///Specifies a section name that can be used to organize parameters in the output.
+
+        /// @param _name is the name of the section, which will be displayed to the user
 		void section(std::string _name)
 		{
 			argsection s;
@@ -283,7 +337,7 @@ namespace stim{
 			sections.push_back(s);
 		}
-        //output the options (generally in response to --help)
+        ///Outputs supported arguments. If ANSI support is available, they will be color-coded. Generally this is called in response to "--help"
         std::string str()
         {
             std::stringstream ss;
@@ -312,6 +366,9 @@ namespace stim{
             return ss.str();
         }
+        ///Retrieves the index for a supported argument, given that argument's name.
+
+        /// @param _name is the name of the requested argument
         int index(std::string _name)
         {
         	unsigned int i = find(opts.begin(), opts.end(), _name) - opts.begin();
@@ -322,6 +379,10 @@ namespace stim{
             return (int)i;
         }
+        ///Sets an argument to a specified value
+
+        /// @param _name is the name of the argument to be set
+        /// @param _value is the value that it is given
         void set(std::string _name, std::string _value)
         {
             int i = index(_name);
@@ -336,7 +397,10 @@ namespace stim{
                 std::cout<<"ERROR - option not recognized: "<<_name<<std::endl;
         }
-        //parse a parameter string
+        ///Parses the command line
+
+        /// @param argc is the number of command line arguments (provided by the OS)
+        /// @param argv[] is the list of command line arguments (provided by the OS)
         void parse(int argc, char* argv[])
         {
             //if the number of options is 1, we're done
@@ -375,7 +439,9 @@ namespace stim{
             set(name, params);
         }
-        //determine if a parameter has been set (either specified by the user or with a default value)
+        ///Determines of a parameter has been set and returns true if it has
+
+        /// @param _name is the name of the argument
         bool operator()(std::string _name)
         {
             int i = find(opts.begin(), opts.end(), _name) - opts.begin();
@@ -389,7 +455,9 @@ namespace stim{
             return opts[i].is_set();
         }
-        //number of arguments in a specified option
+        ///Returns the number of parameters for a specified argument
+
+        /// @param _name is the name of the argument whose parameter number will be returned
         unsigned int nargs(std::string _name)
         {
             int i = find(opts.begin(), opts.end(), _name) - opts.begin();
@@ -403,16 +471,21 @@ namespace stim{
             return opts[i].nargs();
         }
-        //number of arguments for the executable
+        ///Returns the number of arguments that have been set
         unsigned int nargs(){
         	return args.size();
         }
-        //return the a'th executable argument
+        ///Returns the name of an argument, given its index
+
+        /// @param a is the index of the requested argument
         std::string arg(unsigned int a){
         	return args[a];
         }
+        ///Returns an object describing the argument
+
+        /// @param _name is the name of the requested argument
         cmd_option operator[](std::string _name)
         {
             int i = find(opts.begin(), opts.end(), _name) - opts.begin();