Add documentation

README.md

@@ -1,6 +1,10 @@
 # es6-promise-try
 
-A Promise.try shim for ES6 Promises.
+A `Promise.try` shim for ES6 Promises.
+
+`Promise.try` is an important tool for writing robust and readable code with Promises ([this article](http://cryto.net/~joepie91/blog/2016/05/11/what-is-promise-try-and-why-does-it-matter/) explains why), but ES6 Promises do not ([yet](https://github.com/ljharb/proposal-promise-try)) include this in their specification. This module provides an implementation of `Promise.try` for ES6 Promises that can be used stand-alone, without modifying `Promise`'s prototype.
+
+The goal of this module is to be *functionally equivalent* to Bluebird's `Promise.try` implementation. If you find that it behaves differently in some way, please file a bug.
 
 ## License
 
@@ -22,8 +26,22 @@ Be aware that by making a pull request, you agree to release your modifications
 
 ## Usage
 
-TODO
+An example from [the article](http://cryto.net/~joepie91/blog/2016/05/11/what-is-promise-try-and-why-does-it-matter/):
+
+```javascript
+var promiseTry = require("es6-promise-try");
+
+function getUsername(userId) {
+    return promiseTry(function() {
+        return database.users.get({id: userID});
+    }).then(function(user) {
+        return user.name;
+    });
+}
+```
 
 ## API
 
-TODO
+### promiseTry(func)
+
+Immediately invokes `func` - in the same tick of the event loop - and wraps it to provide error-handling and Promises/A+ compatibility, as described in [the article](http://cryto.net/~joepie91/blog/2016/05/11/what-is-promise-try-and-why-does-it-matter/). Functionally equivalent to [Bluebird's `Promise.try`](http://bluebirdjs.com/docs/api/promise.try.html).