Better docs

Author: Daniel Brain

README.md

@@ -1,41 +1,49 @@
 # postRobot
 
-Simple postMessage based server. Good for if you want to use post-messaging between windows, but you don't like the
-fire-and-forget nature of post messages.
+Simple postMessage based server.
 
-With this, you can set up a listener in one window, have it wait for a post message, and then have it reply with data.
+Use this if you want to communicate between two different windows (or popups, or iframes) using `window.postMessage`,
+but you don't like the fire-and-forget nature of the native api.
+
+With this, you can set up a listener in one window, have it wait for a post message, and then have it reply with data,
+and gracefully handle any errors that crop up. You can also set a timeout, to be sure that the other window is responding to you,
+and fail gracefully if it does not.
 
 ## Example
 
-    // In one window
+```javascript
 
-    postRobot.listen({
+// In one window
 
-        name: 'get_cart',
+postRobot.listen({
 
-        handler: function(data, callback) {
-            setTimeout(function() {
-                return callback(null, {
-                    amount: 1,
-                    shipping: 2
-                });
-            }, 3000)
-        }
-    });
+    name: 'get_cart',
+
+    handler: function(data, callback) {
+        setTimeout(function() {
+            return callback(null, {
+                amount: 1,
+                shipping: 2
+            });
+        }, 3000)
+    }
+});
 
-    // In another window
+// In another window
 
-    postRobot.request({
+postRobot.request({
 
-        window: window,
-        name: 'get_cart',
+    window: window,
+    name: 'get_cart',
+
+    response: function(err, data) {
+        if (err) {
+            throw err;
+        }
+        console.log('got cart!', data)
+    },
 
-        response: function(err, data) {
-            if (err) {
-                throw err;
-            }
-            console.log('got cart!', data)
-        },
+    timeout: 1000
+});
 
-        timeout: 1000
-    });
+```