Added documentation - and removed a pub-use

src/app.rs

@@ -5,7 +5,7 @@ use std::collections::HashMap;
 use std::collections::HashSet;
 use std::env;
 
-use ArgMatches;
+use argmatches::ArgMatches;
 use Arg;
 use args::OptArg;
 use args::FlagArg;

src/arg.rs

@@ -1,17 +1,58 @@
+/// The abstract representation of a command line argument used by the consumer of the library.
+/// 
+///
+/// This struct is used by the library consumer and describes the command line arguments for 
+/// their program.
+/// and then evaluates the settings the consumer provided and determines the concret
+/// argument struct to use when parsing.
+///
+/// Example:
+///
+/// ```rust.example
+/// # let matches = App::new("myprog")
+/// #                 .arg(
+/// Arg::new("conifg")
+///       .short("c")
+///       .long("config")
+///       .takes_value(true)
+///       .help("Provides a config file to myprog")
+/// # ).get_matches();
 pub struct Arg {
+	/// The unique name of the argument, required
     pub name: &'static str,
+    /// The short version (i.e. single character) of the argument, no preceding `-`
+    /// **NOTE:** `short` is mutually exclusive with `index`
     pub short: Option<char>,
+    /// The long version of the flag (i.e. word) without the preceding `--`
+    /// **NOTE:** `long` is mutually exclusive with `index`
     pub long: Option<&'static str>,
+    /// The string of text that will displayed to the user when the application's
+    /// `help` text is displayed
     pub help: Option<&'static str>,
+    /// If this is a required by default when using the command line program
+    /// i.e. a configuration file that's required for the program to function
+    /// **NOTE:** required by default means, it is required *until* mutually
+    /// exclusive arguments are evaluated.
     pub required: bool,
+    /// Determines if this argument is an option, vice a flag or positional and
+    /// is mutually exclusive with `index` and `multiple`
     pub takes_value: bool,
+    /// The index of the argument. `index` is mutually exclusive with `takes_value`
+    /// and `multiple`
     pub index: Option<u8>,
+    /// Determines if multiple instances of the same flag are allowed. `multiple` 
+    /// is mutually exclusive with `index` and `takes_value`.
+    /// I.e. `-v -v -v` or `-vvv`
     pub multiple: bool,
+    /// A list of names for other arguments that *may not* be used with this flag
    	pub blacklist: Option<Vec<&'static str>>, 
+    /// A list of names of other arguments that are *required* to be used when 
+    /// this flag is used
     pub requires: Option<Vec<&'static str>>
 }
 
 impl Arg {
+	/// Creates a new instace of and `Arg`
 	pub fn new(n: &'static str) -> Arg {
 		Arg {
 			name: n,

src/args/flagarg.rs

@@ -1,6 +1,7 @@
 /// `FlagArg` represents a flag argument for command line applications. Flag arguments 
 /// take no additional values, and are always preceded by either a `-` (single character)
-/// or `--` (single word, no spaces).
+/// or `--` (single word, no spaces). `FlagArg` isn't directly used by the end application
+/// writer, only internally to the `clap` library.
 /// Example:
 /// ```sh
 /// $ myprog -a --some

src/args/optarg.rs

@@ -1,7 +1,8 @@
 /// `OptArg` represents a option argument for command line applications, which is one that
 /// takes an additional value. Option arguments are always preceded by either a `-` 
 /// (single character) or `--` (single word, no spaces) then followed by a space and the
-/// value.
+/// value.  `OptArg` isn't directly used by the end application
+/// writer, only internally to the `clap` library.
 /// Example:
 /// ```sh
 /// $ myprog -a some --test other --third=file

src/args/posarg.rs

@@ -1,5 +1,6 @@
 /// `PosArg` represents a positional argument, i.e. one that isn't preceded 
-/// by a `-` or `--`. 
+/// by a `-` or `--`. `PosArg` isn't directly used by the end application
+/// writer, only internally to the `clap` library.
 /// Example: 
 /// ```sh
 /// $ myprog some_file

src/lib.rs

@@ -6,7 +6,6 @@
 //! A simply library for parsing command line arguments when writing 
 //! command line and console applications.
 
-pub use argmatches::ArgMatches;
 pub use arg::Arg;
 pub use app::App;