improve comments

index.js

@@ -10,7 +10,12 @@ var moment = require('moment');
 /**
  * Adapter constructor function.
  *
- * @param {Object} config
+ * @example
+   var Adapter = require('lockit-mongodb-adapter');
+   var config = require('./config.js');
+   var adapter = new Adapter(config);
+ *
+ * @param {Object} config - Lockit configuration
  * @constructor
  */
 var Adapter = module.exports = function(config) {
@@ -35,12 +40,29 @@ var Adapter = module.exports = function(config) {
 
 
 /**
- * Create a new user.
+ * Create new user.
+ *
+ * @example
+   adapter.save('john', '[email protected]', 'secret', function(err, user) {
+     if (err) console.log(err);
+     console.log(user);
+     // {
+     //  name: 'john',
+     //  email: 'john@email.com',
+     //  signupToken: 'ef32a95a-d6ee-405a-8e4b-515b235f7c54',
+     //  signupTimestamp: Wed Jan 15 2014 19:08:27 GMT+0100 (CET),
+     //  signupTokenExpires: Wed Jan 15 2014 19:08:27 GMT+0100 (CET),
+     //  failedLoginAttempts: 0,
+     //  salt: '48cf9da376703199c30ba5c274580c98',
+     //  derived_key: '502967e5a6e55091f4c2c80e7989623f051070fd',
+     //  _id: 52d6ce9b651b4d825351641f
+     // }
+   });
  *
- * @param {String} name
- * @param {String} email
- * @param {String} pw
- * @param {Function} done
+ * @param {String} name - User name
+ * @param {String} email - User email
+ * @param {String} pw - Plain text user password
+ * @param {Function} done - Callback function `function(err, user){}`
  */
 Adapter.prototype.save = function(name, email, pw, done) {
   var that = this;
@@ -72,9 +94,26 @@ Adapter.prototype.save = function(name, email, pw, done) {
 /**
  * Find user. Match is either `name`, `email` or `signupToken`.
  *
- * @param {String} match
- * @param {String} query
- * @param {Function} done
+ * @example
+   adapter.find('name', 'john', function(err, user) {
+     if (err) console.log(err);
+     console.log(user);
+     // {
+     //   name: 'john',
+     //   email: 'john@email.com',
+     //   signupToken: '3a7f0f54-32f0-44f7-97c6-f1470b94c170',
+     //   signupTimestamp: Fri Apr 11 2014 21:31:54 GMT+0200 (CEST),
+     //   signupTokenExpires: Sat Apr 12 2014 21:31:54 GMT+0200 (CEST),
+     //   failedLoginAttempts: 0,
+     //   salt: '753981e8d8e30e8047cf5685d1f0a0d4',
+     //   derived_key: '18ce03eddab6729aeaaf76729c90cb31f16a863c',
+     //   _id: 5348432a98a8a6a4fef1f595
+     // }
+   });
+ *
+ * @param {String} match - Property to find user by. `name`, `email` or `signupToken`
+ * @param {String} query - Corresponding value to `match`
+ * @param {Function} done - Callback function `function(err, user){}`
  */
 Adapter.prototype.find = function(match, query, done) {
   var qry = {};
@@ -87,14 +126,30 @@ Adapter.prototype.find = function(match, query, done) {
 /**
  * Update existing user.
  *
- * @param {Object} user
- * @param {Function} done
+ * @example
+   // get user from db
+   adapter.find('name', 'john', function(err, user) {
+     if (err) console.log(err);
+
+     // add some new properties
+     user.newKey = 'and some value';
+     user.hasBeenUpdated = true;
+
+     // save updated user to db
+     adapter.update(user, function(err, user) {
+       if (err) console.log(err);
+       // ...
+     });
+   });
+ *
+ * @param {Object} user - Existing user from db
+ * @param {Function} done - Callback function `function(err, user){}`
  */
 Adapter.prototype.update = function(user, done) {
   var that = this;
   // update user in db
   that.db.collection(that.collection).save(user, function(err, res) {
-    if (err) console.log(err);
+    if (err) return done(err);
     // res is not the updated user object! -> find manually
     that.db.collection(that.collection).find({_id: user._id}).nextObject(done);
   });
@@ -105,8 +160,15 @@ Adapter.prototype.update = function(user, done) {
 /**
  * Delete existing user.
  *
- * @param {String} name
- * @param {Function} done
+ * @example
+   adapter.remove('john', function(err, res) {
+     if (err) console.log(err);
+     console.log(res);
+     // true
+   });
+ *
+ * @param {String} name - User name
+ * @param {Function} done - Callback function `function(err, res){}`
  */
 Adapter.prototype.remove = function(name, done) {
   this.db.collection(this.collection).remove({name: name}, function(err, numberOfRemovedDocs) {