Better documentation.

README.md

@@ -1,12 +1,76 @@
 # mongoson: MongoDB Shell Object Notation
 
-An alternative for JSON.stringify. It serializes queries (and data to be inserted or updated) in such a way that they can be pasted into the Mongo shell, with no loss of fidelity. 
+MSON.stringify is an alternative for JSON.stringify. It serializes queries (and data to be inserted or updated) in such a way that they can be pasted into the Mongo shell, with no loss of fidelity. 
+
+The primary use case is to help with MongoDB debugging queries that are generated by your app.
 
 At this moment, it encodes ObjectId, DBRef and Date objects. All else should be equivalent to regular JSON.
 
+## Installation
+
+```
+npm install mongoson
+```
+
 ## Usage
 
+### MSON.stringify
+
 ```coffee
 MSON = require 'mongoson'
 MSON.stringify mongoQuery
-```
+```
+
+This returns a serialized query, a query "object literal" of some sort. The result can be pasted into the mongo console.
+
+### MSON.parseUnsafe
+
+For the brave-at-heart, there's also `MSON.parseUnsafe serializedQuery`. It's called `parseUnsafe` for a reason, because it actually uses `eval` to instantiate the correct `ObjectId`, `DBRef` and `Date` objects, *without doing any sanitation beforehand*. You do NOT want to use this unattended. Before running it on any serialized query, I recommend scrutinizing it for any fishy stuff inside. _It could absolutely execute any kind of code in node.js._
+
+The advantage of `MSON.parseUnsafe` over doing eval yourself is that the code gets evaluated in a context where `ObjectId`, `DBRef`, and `ISODate` functions are defined. This is quicker than importing them from MongoDB's BSON module yourself.
+
+I'd appreciate any hints on how to adjust (for example) the [JSON2](https://github.com/douglascrockford/JSON-js) parse function to let the specific calls to ObjectId, DBRef and ISODate pass through, while denying any other kinds of expression (beyond valid JSON expressions, obviously). Then we could have a safe `MSON.parse`.
+
+## Example
+
+Suppose you have build a query using some "native" Mongo object types (DBRef and ObjectId), like so:
+
+```coffee
+bson = require 'bson'
+ObjectID = bson.BSONPure.ObjectID
+DBRef = bson.BSONPure.DBRef
+
+someQuery = 
+  _id: ObjectID("507f1f77bcf86cd799439011")
+  title: "Super"
+  related: [
+    ObjectID("507f1f77bcf86cd799439011"), 
+    ObjectID("507f1f77bcf86cd799439012"), 
+    ObjectID("507f1f77bcf86cd799439013")
+  ]
+  owner: DBRef("groups",ObjectID("507f191e810c19729de860ea"))
+  updatedAt: 
+    $gte: new Date "2012-02-07T18:32:42.692Z" 
+    $lte: new Date "2013-02-07T18:32:42.692Z"
+```
+
+You can then do
+
+```coffee
+console.log MSON.stringify original
+```
+
+Which gives
+
+```javascript
+{"_id":ObjectId("507f1f77bcf86cd799439011"),"title":"Super","related":[ObjectId("507f1f77bcf86cd799439011"),ObjectId("507f1f77bcf86cd799439012"),ObjectId("507f1f77bcf86cd799439013")],"owner":{"$ref":"groups","$id":"507f191e810c19729de860ea"},"updatedAt":{"$gte":ISODate("2012-02-07T18:32:42.692Z"),"$lte":ISODate("2013-02-07T18:32:42.692Z")}}
+```
+
+This is ready to be pasted into the MongoDB shell as part of a command.
+
+The example input and output is taken straight from the (sole) test for this module, so the above should absolutely work.
+
+## License
+
+mongoson is released under the [MIT License](http://opensource.org/licenses/MIT).  
+Copyright (c) 2013 Meryn Stol