@@ -11,7 +11,7 @@
, Schema = require('./schema')
, utils = require('./utils')
, isMongooseObject = utils.isMongooseObject
- , EventEmitter = utils.EventEmitter
+ , EventEmitter = require('events').EventEmitter
, merge = utils.merge
, Promise = require('./promise')
, tick = utils.tick
@@ -795,7 +795,7 @@
Model.schema;
/**
- * Database instance the model uses.
+ * Connection instance the model uses.
*
* @property db
* @receiver Model
@@ -827,11 +827,18 @@
/**
* Removes documents from the collection.
*
+ * ####Example:
+ *
+ * Comment.remove({ title: 'baby born from alien father' }, function (err) {
+ *
+ * });
+ *
* ####Note:
*
* To remove documents without waiting for a response from MongoDB, do not pass a `callback`, then call `exec` on the returned [Query](#query-js):
*
- * Comment.remove({ _id: id }).exec();
+ * var query = Comment.remove({ _id: id });
+ * query.exec();
*
* ####Note:
*
@@ -861,13 +868,33 @@
/**
* Finds documents
*
+ * The `conditions` are cast to their respective SchemaTypes before the command is sent.
+ *
* ####Examples:
*
- * // retrieve only certain keys
- * MyModel.find({ name: /john/i }, 'name friends', function () { })
+ * // named john and at least 18
+ * MyModel.find({ name: 'john', age: { $gte: 18 }});
+ *
+ * // executes immediately, passing results to callback
+ * MyModel.find({ name: 'john', age: { $gte: 18 }}, function (err, docs) {});
+ *
+ * // name LIKE john and only selecting the "name" and "friends" fields, executing immediately
+ * MyModel.find({ name: /john/i }, 'name friends', function (err, docs) { })
+ *
+ * // passing options
+ * MyModel.find({ name: /john/i }, null, { skip: 10 })
+ *
+ * // passing options and executing immediately
+ * MyModel.find({ name: /john/i }, null, { skip: 10 }, function (err, docs) {});
+ *
+ * // executing a query explicitly
+ * var query = MyModel.find({ name: /john/i }, null, { skip: 10 })
+ * query.exec(function (err, docs) {});
*
- * // pass options
- * MyModel.find({ name: /john/i }, null, { skip: 10 } )
+ * // using the promise returned from executing a query
+ * var query = MyModel.find({ name: /john/i }, null, { skip: 10 });
+ * var promise = query.exec();
+ * promise.addBack(function (err, docs) {});
*
* @param {Object} conditions
* @param {Object} [fields] optional fields to select
@@ -875,6 +902,7 @@
* @param {Function} [callback]
* @return {Query}
* @see field selection #query_Query-select
+ * @see promise #promise-js
* @api public
*/
@@ -930,11 +958,30 @@
/**
* Finds a single document by id.
*
- * The `id` is cast to an ObjectId before sending the command.
+ * The `id` is cast based on the Schema before sending the command.
*
* ####Example:
*
- * Adventure.findById(id, callback);
+ * // find adventure by id and execute immediately
+ * Adventure.findById(id, function (err, adventure) {});
+ *
+ * // same as above
+ * Adventure.findById(id).exec(callback);
+ *
+ * // select only the adventures name and length
+ * Adventure.findById(id, 'name length', function (err, adventure) {});
+ *
+ * // same as above
+ * Adventure.findById(id, 'name length').exec(callback);
+ *
+ * // include all properties except for `length`
+ * Adventure.findById(id, '-length').exec(function (err, adventure) {});
+ *
+ * // passing options (in this case return the raw js objects, not mongoose documents by passing `lean`
+ * Adventure.findById(id, 'name', { lean: true }, function (err, doc) {});
+ *
+ * // same as above
+ * Adventure.findById(id, 'name').lean().exec(function (err, doc) {});
*
* @param {ObjectId|HexId} id objectid, or a value that can be casted to one
* @param {Object} [fields] optional fields to select
@@ -942,6 +989,7 @@
* @param {Function} [callback]
* @return {Query}
* @see field selection #query_Query-select
+ * @see lean queries #query_Query-lean
* @api public
*/
@@ -956,7 +1004,26 @@
*
* ####Example:
*
- * Adventure.findOne({ type: 'iphone' }, 'name', { safe: true }, callback);
+ * // find one iphone adventures - iphone adventures??
+ * Adventure.findOne({ type: 'iphone' }, function (err, adventure) {});
+ *
+ * // same as above
+ * Adventure.findOne({ type: 'iphone' }).exec(function (err, adventure) {});
+ *
+ * // select only the adventures name
+ * Adventure.findOne({ type: 'iphone' }, 'name', function (err, adventure) {});
+ *
+ * // same as above
+ * Adventure.findOne({ type: 'iphone' }, 'name').exec(function (err, adventure) {});
+ *
+ * // specify options, in this case lean
+ * Adventure.findOne({ type: 'iphone' }, 'name', { lean: true }, callback);
+ *
+ * // same as above
+ * Adventure.findOne({ type: 'iphone' }, 'name', { lean: true }).exec(callback);
+ *
+ * // chaining findOne queries (same as above)
+ * Adventure.findOne({ type: 'iphone' }).select('name').lean().exec(callback);
*
* @param {Object} conditions
* @param {Object} [fields] optional fields to select
@@ -964,6 +1031,7 @@
* @param {Function} [callback]
* @return {Query}
* @see field selection #query_Query-select
+ * @see lean queries #query_Query-lean
* @api public
*/
@@ -1074,7 +1142,7 @@
*
* Sometimes you need to query for things in mongodb using a JavaScript expression. You can do so via `find({ $where: javascript })`, or you can use the mongoose shortcut method $where via a Query chain or from your mongoose Model.
*
- * Blog.$where('this.comments.length > 5');
+ * Blog.$where('this.comments.length > 5').exec(function (err, docs) {});
*
* @param {String|Function} argument is a javascript string or anonymous function
* @method $where