README updates

Author: kylef

README.md

@@ -23,6 +23,16 @@ main.run()
 
 ##### Type-safe argument handling
 
+The closure passed to the command function takes any arguments that
+conform to `ArgumentConvertible`, Commander will automatically convert the
+arguments to these types. If they can't be converted the user will receive a
+nice error message informing them that their argument doesn't match the
+expected type.
+
+`String`, `Int`, `Double`, and `Float` are extended to conform to
+`ArgumentConvertible`, you can easily extend any other class or structure
+so you can use it as an argument to your command.
+
 ```swift
 command { (hostname:String, port:Int) in
   print("Connecting to \(hostname) on port \(port)...")
@@ -48,19 +58,30 @@ Group {
 Usage:
 
 ```shell
-$ tool login Kyle
+$ auth
+Usage:
+
+    $ auth COMMAND
+
+Commands:
+
+    + login
+    + logout
+
+$ auth login Kyle
 Hello Kyle
-$ tool logout
+$ auth logout
 Goodbye.
 ```
 
 #### Describing arguments
 
-You can describe arguments and options for a command to auto-generate help.
+You can describe arguments and options for a command to auto-generate help,
+this is done by passing in descriptors of these arguments.
 
 For example, to describe a command which takes two options, `--name` and
-`--count` where the default value for name is "world" and the default value for
-count is 1.
+`--count` where the default value for name is `world` and the default value for
+count is `1`.
 
 ```swift
 command(
@@ -74,31 +95,38 @@ command(
 ```
 
 ```shell
-./hello --help
+$ hello --help
 Usage:
 
-    $ ./hello
+    $ hello
 
 Options:
     --name
     --count - The number of times to print.
 
-./hello
+$ hello
 Hello world
 
-./hello --name Kyle
+$ hello --name Kyle
 Hello Kyle
 
-./hello --name Kyle --count 4
+$ hello --name Kyle --count 4
 Hello Kyle
 Hello Kyle
 Hello Kyle
 Hello Kyle
 ```
 
+##### Types of descriptors
+
+- Argument - A positional argument.
+- Option - An optional option with a value.
+- Flag - A boolean, on/off flag.
+
 #### Using the argument parser
 
-You can get hold of the argument parser to do custom argument handling
+**NOTE**: *`ArgumentParser` itself is `ArgumentConvertible` so you can also
+get hold of the raw argument parser to perform any custom parsing.*
 
 ```swift
 command { (name:String, parser:ArgumentParser) in
@@ -149,6 +177,40 @@ let main = command {
 main.run()
 ```
 
+### Architecture
+
+##### `CommandType`
+
+`CommandType` is the core protocol behind commands, it's an object or
+structure that has a `run` method which takes an `ArgumentParser`.
+
+Both the `command` functions and `Group` return a command that conforms to
+`CommandType` which can easily be interchanged.
+
+```swift
+protocol CommandType {
+  func run(parser:ArgumentParser) throws
+}
+```
+
+##### `ArgumentConvertible`
+
+The convenience `command` function takes a closure for your command that
+takes arguments which conform to the `ArgumentConvertible` protocol. This
+allows Commander to easily convert arguments to the types you would like
+to use for your command.
+
+```swift
+protocol ArgumentConvertible {
+  init(parser: ArgumentParser) throws
+}
+```
+
+##### `ArgumentParser`
+
+The `ArgumentParser` is an object that allowing you to pull out options,
+flags and positional arguments.
+
 ## License
 
 Commander is available under the BSD license. See the [LICENSE file](LICENSE)