documentation update

- Noting availability of beforeMoment and afterMoment assertions
- Explanation of granularities
- Example code

README.md

@@ -18,20 +18,95 @@ include chai moment after chai and moment:
 
 have chai use chai-moment:
 
-    var chai = require('chai');
-    chai.use(require('chai-moment'));
+```javascript
+
+var chai = require('chai');
+chai.use(require('chai-moment'));
+
+```
 
 ## Assertions
 
+Compare any moment-parseable date/string/whatever with another, with optional granularity.  See [Moment.js docs](http://momentjs.com/docs/#/parsing/) on parsing.
 
-### sameMoment(date[, granularity])
+When using granularity, please use one of the following: `year`, `month`, `week`, `day`, `hour`, `minute`, `second`.  When using tdd-style assertions, if you do not use one of the listed granularities, the argument will be interpreted as a custom error message.
 
-compare any moment-parseable date/string/whatever with another, with optional granularity.
+### sameMoment
 
 ```javascript
 
+var dateString = '2016-04-21',
+    date = new Date(2016, 3, 21),
+    milliseconds = 1461222000000,  // assumes system has PDT timezone
+    obj = { y: 2016, M: 3, d: 21 },
+    arr = [2016, 3, 21],
+    momentObj = moment('2016-04-21'),
+    oneDayLater = '2016-04-22';
+
+// using should-style assertions
+dateString.should.be.sameMoment(date);
+dateString.should.be.sameMoment(oneDayLater, 'month');
+
+// using expect-style assertions
+expect(milliseconds).to.be.sameMoment(obj);
+expect(dateString).to.be.sameMoment(oneDayLater, 'month');
+
+// using tdd assertions
+assert.sameMoment(arr, momentObj);
+assert.sameMoment(arr, oneDayLater, 'month');
+assert.sameMoment(arr, oneDayLater, 'month', 'custom error message');
+assert.sameMoment(arr, oneDayLater, 'custom error message');  // fails
+
 ```
 
+### beforeMoment
+
+```javascript
+
+var dateString = '2016-04-21',
+    oneDayLater = '2016-04-22';
+
+// using should-style assertions
+dateString.should.be.beforeMoment(oneDayLater);
+dateString.should.be.beforeMoment(oneDayLater, 'month');  // fails
+
+// using expect-style assertions
+expect(dateString).to.be.beforeMoment(oneDayLater);
+expect(dateString).to.be.beforeMoment(oneDayLater, 'month');  // fails
+
+// using tdd assertions
+assert.beforeMoment(dateString, oneDayLater);
+assert.beforeMoment(dateString, oneDayLater, 'month');  // fails
+assert.beforeMoment(dateString, oneDayLater, 'month', 'custom error message');  // fails
+assert.beforeMoment(dateString, oneDayLater, 'custom error message');
+
+```
+
+### afterMoment
+
+```javascript
+
+var dateString = '2016-04-21',
+    oneDayLater = '2016-04-22';
+
+// using should-style assertions
+oneDayLater.should.be.afterMoment(dateString);
+oneDayLater.should.be.afterMoment(dateString, 'month');  // fails
+
+// using expect-style assertions
+expect(oneDayLater).to.be.afterMoment(dateString);
+expect(oneDayLater).to.be.afterMoment(dateString, 'month');  // fails
+
+// using tdd assertions
+assert.afterMoment(oneDayLater, dateString);
+assert.afterMoment(oneDayLater, dateString, 'month');  // fails
+assert.afterMoment(oneDayLater, dateString, 'month', 'custom error message');  // fails
+assert.afterMoment(oneDayLater, dateString, 'custom error message');
+
+```
+
+
+
 # Thanks
 
 Thanks to [chai-fuzzy](https://github.com/elliotf/chai-fuzzy) for the project structure.