Added documentation and fixed some bugs

src/app.rs

@@ -11,10 +11,35 @@ use args::OptArg;
 use args::FlagArg;
 use args::PosArg;
 
+/// Used to create a representation of the program and all possible command line arguments
+/// for parsing at runtime.
+///
+///
+/// Stores a list of all posisble arguments, as well as information displayed to the user such as
+/// help and versioning information.
+///
+/// Example:
+///
+/// ```rust.example
+/// let myprog = App::new("myprog")
+///                   .author("Me, me@mail.com")
+///	                  .version("1.0.2")
+///                   .about("Explains in brief what the program does")
+///                   .arg(
+///                        // Add a possible command line argument
+///                    )
+///                   .get_matches();
+///
+/// // Your pogram logic starts here...
+/// ```
 pub struct App {
+	/// The name displayed to the user when showing version and help/usage information
 	pub name: &'static str,
+	/// A string of author(s) if desired. Displayed when showing help/usage information
 	pub author: Option<&'static str>,
+	/// The version displayed to the user
 	pub version: Option<&'static str>,
+	/// A brief explaination of the program that gets displayed to the user when shown help/usage information
 	pub about: Option<&'static str>,
 	flags: HashMap<&'static str, FlagArg>,
 	opts: HashMap<&'static str, OptArg>,
@@ -30,6 +55,14 @@ pub struct App {
 }
 
 impl App {
+	/// Creates a new instance of an application requiring a name (such as the binary). Will be displayed
+	/// to the user when they print version or help and usage information.
+	///
+	/// Example:
+	///
+	/// ```rust.example
+	/// let prog = App::new("myprog");
+	/// ```
 	pub fn new(n: &'static str) -> App {
 		App {
 			name: n,
@@ -50,21 +83,51 @@ impl App {
 		}
 	}
 
+	/// Sets a string of author(s)
+	///
+	/// Example:
+	///
+	/// ```rust.example
+	/// .author("Kevin <kbknapp@gmail.com>");
+	/// ```
 	pub fn author(&mut self, a: &'static str) -> &mut App {
 		self.author = Some(a);
 		self
 	}
 
+	/// Sets a string briefly describing what the program does
+	///
+	/// Example:
+	///
+	/// ```rust.example
+	/// .about("Does really amazing things to great people");
+	/// ```
 	pub fn about(&mut self, a: &'static str) -> &mut App {
 		self.about = Some(a);
 		self
 	}
 
+	/// Sets a string of the version number
+	///
+	/// Example:
+	///
+	/// ```rust.example
+	/// .version("v0.1.24");
+	/// ```
 	pub fn version(&mut self, v: &'static str)-> &mut App  {
 		self.version = Some(v);
 		self
 	}
 
+	/// Adds an argument to the list of valid possibilties
+	///
+	/// Example:
+	///
+	/// ```rust.example
+	/// .arg(Arg::new("config")
+	///     // Additional argument configuration goes here...
+	/// );
+	/// ```
 	pub fn arg(&mut self, a: &Arg) -> &mut App {
 		if self.arg_list.contains(a.name) {
 			panic!("Argument name must be unique, \"{}\" is already in use", a.name);
@@ -92,6 +155,9 @@ impl App {
 				value: None
 			});
 		} else if a.takes_value {
+			if a.short == None && a.long == None {
+				panic!("An argument that takes a value must have either a .short() or .long() [or both] assigned");
+			}
 			self.opts.insert(a.name, OptArg {
 				name: a.name,
 				short: a.short,
@@ -117,6 +183,9 @@ impl App {
 					self.needs_short_version = false;
 				}
 			}
+			if a.short == None && a.long == None {
+				panic!("A flag argument must have either a .short() or .long() [or both] assigned");
+			}
 			// Flags can't be required
 			if self.required.contains(a.name) {
 				self.required.remove(a.name);
@@ -135,6 +204,14 @@ impl App {
 		self
 	}
 
+	/// Adds arguments to the list of valid possibilties
+	///
+	/// Example:
+	///
+	/// ```rust.example
+	/// .args( vec![Arg::new("config").short("c"),
+	///				Arg::new("debug").short("d")]);
+	/// ```
 	pub fn args(&mut self, args: Vec<&Arg>) -> &mut App {
 		for arg in args.iter() {
 			self.arg(arg);

src/arg.rs

@@ -84,6 +84,11 @@ impl Arg {
 
 	/// Sets the short version of the argument without the preceding `-`.
 	///
+	///
+	/// By default `clap` automatically assigns `v` and `h` to display version and help information 
+	/// respectivly. You may use `v` or `h` for your own purposes, in which case `clap` simply
+	/// will not asign those to the displaying of version or help.
+	///
 	/// **NOTE:** Any leading `-` characters will be stripped, and only the first
 	/// non `-` chacter will be used as the `short` version, i.e. for when the user
 	/// mistakenly sets the short to `-o` or the like.
@@ -103,6 +108,11 @@ impl Arg {
 
 	/// Sets the long version of the argument without the preceding `--`.
 	///
+	/// By default `clap` automatically assigns `version` and `help` to display version and help information 
+	/// respectivly. You may use `version` or `help` for your own purposes, in which case `clap` simply
+	/// will not asign those to the displaying of version or help automatically, and you will have to do
+	/// so manually.
+	///
 	/// **NOTE:** Any leading `-` characters will be stripped i.e. for 
 	/// when the user mistakenly sets the short to `--out` or the like.
 	///

src/argmatches.rs

@@ -4,7 +4,7 @@ use std::collections::HashSet;
 use app::App;
 use args::{ FlagArg, OptArg, PosArg };
 
-/// `ArgMatches` is used to get information about the arguments that
+/// Used to get information about the arguments that
 /// where supplied to the program at runtime.
 ///
 ///

src/lib.rs

@@ -1,10 +1,62 @@
-#![crate_id = "clap"]
 #![crate_type= "lib"]
 
 #![feature(collections, core, libc, env)]
 
 //! A simply library for parsing command line arguments when writing 
 //! command line and console applications.
+//!
+//!
+//! You can use `clap` to lay out a list of possible valid command line arguments and let `clap` parse the string given by the user at runtime.
+//! When using `clap` you define a set of parameters and rules for your arguments and at runtime `clap` will determine their validity.
+//! Also, `clap` provides the traditional version and help switches 'for free' by parsing the list of possible valid arguments lazily at runtime.
+//! i.e. only when it's been determined that the user wants or needs to see the help and version information.
+//! 
+//! After defining a list of possible valid arguments you get a list of matches that the user supplied at runtime. You can then use this list to
+//! determine the functioning of your program.
+//!
+//! Example:
+//! 
+//! ```rust.example
+//! extern crate clap;
+//! use clap::{Arg, App};
+//!
+//! // ...
+//! 
+//! let matches = App::new("MyApp")
+//!						.version("1.0")
+//!						.author("Kevin K. <kbknapp@gmail.com>")
+//!						.about("Does awesome things")
+//!						.arg(Arg::new("config")
+//!									.short("c")
+//!									.long("config")
+//!									.help("Sets a custom config file")
+//!									.takes_value(true))
+//!						.arg(Arg::new("output")
+//!									.help("Sets an optional output file")
+//!									.index(1)
+//!						.arg(Arg::new("debug")
+//!									.short("d")
+//! 								.multiple(true)
+//!									.help("Turn debugging information on"))
+//!						.get_matches();
+//!
+//!	if let Some(o) = matches.value_of("output") {
+//!		println!("Value for output: {}", o);
+//!	}
+//! 
+//!	if let Some(c) = matches.value_of("config") {
+//!		println!("Value for config: {}", c);
+//!	}
+//!
+//! match matches.occurrences_of("debug") {
+//! 	0 => println!("Debug mode is off"),
+//!		1 => println!("Debug mode is kind of on"),
+//!		2 => println!("Debug mode is on"),
+//!		3 | _ => println!("Don't be crazy"),
+//! }
+//! 
+//! // more porgram logic goes here...
+//! ```
 
 pub use argmatches::ArgMatches;
 pub use arg::Arg;