Formally describe API. Add "why" section.

README.md

@@ -1,11 +1,22 @@
 redis - a node redis client
 ===========================
 
-This is a Redis client for node.  It is designed for node 0.2.1+ and redis 2.0.1+.
+This is a Redis client for node.  It is designed for node 0.2.1+ and redis 2.0.1+.  It probably won't work on earlier versions of either.
 
 Most Redis commands are implemented, including MULTI.  The notable exceptions are PUBLISH/SUBSCRIBE, and WATCH/UNWATCH.
 These should be coming soon.
 
+## Why?
+
+`node_redis` works in the latest versions of node, is published in `npm`, and is very fast.
+
+The most popular Redis client, `redis-node-client` by fictorial, is very mature and well tested.  If you are running an older version
+of node or value the maturity and stability of `redis-node-client`, I encourage you to use that one instead.
+
+`node_redis` is designed with performance in mind.  The included `test.js` runs similar tests to `redis-benchmark`, included with the Redis 
+distribution, and `test.js` is faster for some patterns and slower for others.  `node_redis` is roughly 6X faster at these benchmarks
+than `redis-node-client`.
+
 ## Usage
 
 Simple example:
@@ -36,15 +47,6 @@ This will display:
     HSET: 1
     HKEYS: hashtest 1,hashtest 2
 
-
-### Creating a new Client Connection
-
-Use `redis.createClient(port, host)` to create a new client connection.  `port` defaults to `6379` and `host` defaults
-to `127.0.0.1`.  If you have Redis running on the same computer as node, then the defaults are probably fine.
-
-`createClient` returns a `RedisClient` object that is named `client` in all of the examples here.
-
-
 ### Sending Commands
 
 Each Redis command is exposed as a function on the `client` object.
@@ -89,6 +91,103 @@ transaction.
 
 I guess we also need a callback when `MULTI` finishes, in case the last command gets removed from an error.
 
+# API
+
+## Events
+
+`client` will emit some events about the state of the connection to the Redis server.
+
+### `connect`
+
+`client` will emit `connect` when a connection is established to the Redis server.
+
+### `error`
+
+`client` will emit `error` when encountering an error connecting to the Redis server.
+
+### `end`
+
+`client` will emit `end` when an established Redis server connection has closed.
+
+## redis.createClient(port, host)
+
+Create a new client connection.  `port` defaults to `6379` and `host` defaults
+to `127.0.0.1`.  If you have Redis running on the same computer as node, then the defaults are probably fine.
+
+`createClient` returns a `RedisClient` object that is named `client` in all of the examples here.
+
+
+## `client.end()`
+
+Close the connection to the Redis server.  Note that this does not wait until all replies have been parsed.
+If you want to exit cleanly, call `client.end()` in the reply callback of your last command:
+
+    var redis = require("redis"),
+        client = redis.createClient();
+
+    client.on("connect", function () {
+        client.set("foo_rand000000000000", "some fantastic value");
+        client.get("foo_rand000000000000", function (err, reply) {
+            console.log(reply.toString());
+            client.end();
+        });
+    });
+
+## `redis.print()`
+
+A handy callback function for displaying return values when testing.  Example:
+
+    var redis = require("redis"),
+        client = redis.createClient();
+
+    client.on("connect", function () {
+        client.set("foo_rand000000000000", "some fantastic value", redis.print);
+        client.get("foo_rand000000000000", redis.print);
+    });
+
+This will print:
+
+    Reply: OK
+    Reply: some fantastic value
+
+Note that this program will not exit cleanly because the client is still connected.
+
+## `redis.debug_mode`
+
+Boolean to enable debug mode and protocol tracing.
+
+    var redis = require("redis"),
+        client = redis.createClient();
+
+    redis.debug_mode = true;
+
+    client.on("connect", function () {
+        client.set("foo_rand000000000000", "some fantastic value");
+    });
+
+This will display:
+
+    mjr:~/work/node_redis (master)$ node ~/example.js 
+    send command: *3
+    $3
+    SET
+    $20
+    foo_rand000000000000
+    $20
+    some fantastic value
+
+    on_data: +OK
+
+`send command` is data sent into Redis and `on_data` is data received from Redis.
+
+## `client.send_command(command_name, args, callback)`
+
+Used internally to send commands to Redis.  For convenience, nearly all commands that are published on the Redis 
+Wiki have been added to the `client` object.  However, if I missed any, or if new commands are introduced before
+this library is updated, you can use `send_command()` to send arbitrary commands to Redis.
+
+All commands are sent a multi-bulk commands.  `args` can either be an Array of arguments, or individual arguments,
+or omitted completely.
 
 ## TODO