Added doxygen file header with description of the library design and behavior

diff --git a/source/opts.h b/source/opts.h
index 75194810cd9595fb7dea277328b65e5d7e895142..18a0e54b234735b349478f1daa5704b06b28a049 100755 (executable)
--- a/source/opts.h
+++ b/source/opts.h
@@ -1,3 +1,44 @@
+/**
+ * @file
+ * @author Mike D. Lowis
+ *
+ * This project is an implementation of a very lightweight command-line options
+ * parser. It is capable of interpreting the Unix/GNU style command line
+ * argument flags. It is designed to be platform independent and can be used as
+ * a static library or directly as source.
+ *
+ * The library is designed to work like something of a database for your
+ * command line. At initialization time you feed in the arguments vector (your
+ * data records) and a list of option definitions (your schema). The library
+ * then parses the options and stores them internally for querying later.
+ * Several querying functions are provided that cover the most common use cases
+ * for options handling.
+ *
+ * All of the query functions take an option name and an option tag as
+ * parameters. These two arguments will be used to search the list of parsed
+ * options for any that match both parameters. In some cases only one of the
+ * parameters is needed for a query. To facilitate this, the query functions
+ * will interpret a NULL pointer to match everything. An example of this would
+ * be selecting all parsed options with the tag "foo":
+ *
+ * const char** foo_lst = opts_select(NULL,"foo");
+ *
+ * In the example above, the NULL would match *all* parsed options and from that
+ * group only those having the tag "foo" would be returned. Another common
+ * scenario would be searching by parameter name:
+ *
+ * const char** includes = opts_select("I", NULL);
+ *
+ * In this scenario all of the options that were parsed having the name 'I'
+ * would be returned regardless of their tag value. This would equate to all of
+ * the instances of '-I' that would occur on the command line for an invocation
+ * of gcc.
+ *
+ * With this design you should be able to let the library handle your options
+ * parsing while you focus on your application logic using appropriate queries
+ * to change behavior where necessary.
+ *
+ */
 #ifndef OPTS_H
 #define OPTS_H
 
@@ -11,7 +52,7 @@ extern "C" {
 
 /** Structure representing an option to be parsed */
 typedef struct {
-    /** The name of the option as it will appear on the commandline */
+    /** The name of the option as it will appear on the command line */
     char* name;
     /** Flag indicating whether the option expects an argument or not */
     bool has_arg;