docs(model): make find and findOne() examples use async/await and…

… clarify `find({})` is find all

Fix #9210

lib/model.js

@@ -1976,35 +1976,26 @@ Model.deleteMany = function deleteMany(conditions, options, callback) {
 /**
  * Finds documents.
  *
- * The `filter` are cast to their respective SchemaTypes before the command is sent.
+ * Mongoose casts the `filter` to match the model's schema before the command is sent.
  * See our [query casting tutorial](/docs/tutorials/query_casting.html) for
  * more information on how Mongoose casts `filter`.
  *
  * ####Examples:
  *
- *     // named john and at least 18
- *     MyModel.find({ name: 'john', age: { $gte: 18 }});
+ *     // find all documents
+ *     await MyModel.find({});
+ *
+ *     // find all documents named john and at least 18
+ *     await MyModel.find({ name: 'john', age: { $gte: 18 } }).exec();
  *
  *     // executes, passing results to callback
  *     MyModel.find({ name: 'john', age: { $gte: 18 }}, function (err, docs) {});
  *
  *     // executes, name LIKE john and only selecting the "name" and "friends" fields
- *     MyModel.find({ name: /john/i }, 'name friends', function (err, docs) { })
+ *     await MyModel.find({ name: /john/i }, 'name friends').exec();
  *
  *     // passing options
- *     MyModel.find({ name: /john/i }, null, { skip: 10 })
- *
- *     // passing options and executes
- *     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) {});
- *
- *     // 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) {});
+ *     await MyModel.find({ name: /john/i }, null, { skip: 10 }).exec();
  *
  * @param {Object|ObjectId} filter
  * @param {Object|String} [projection] optional fields to return, see [`Query.prototype.select()`](http://mongoosejs.com/docs/api.html#query_Query-select)
@@ -2067,26 +2058,14 @@ Model.find = function find(conditions, projection, options, callback) {
  *
  * ####Example:
  *
- *     // find adventure by id and execute
- *     Adventure.findById(id, function (err, adventure) {});
+ *     // Find the adventure with the given `id`, or `null` if not found
+ *     await Adventure.findById(id).exec();
  *
- *     // same as above
- *     Adventure.findById(id).exec(callback);
+ *     // using callback
+ *     Adventure.findById(id, function (err, adventure) {});
  *
  *     // 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) {});
+ *     await Adventure.findById(id, 'name length').exec();
  *
  * @param {Any} id value of `_id` to query by
  * @param {Object|String} [projection] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
@@ -2122,26 +2101,14 @@ Model.findById = function findById(id, projection, options, callback) {
  *
  * ####Example:
  *
- *     // 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) {});
+ *     // Find one adventure whose `country` is 'Croatia', otherwise `null`
+ *     await Adventure.findOne({ country: 'Croatia' }).exec();
  *
- *     // same as above
- *     Adventure.findOne({ type: 'iphone' }, 'name').exec(function (err, adventure) {});
+ *     // using callback
+ *     Adventure.findOne({ country: 'Croatia' }, 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);
+ *     // select only the adventures name and length
+ *     await Adventure.findOne({ country: 'Croatia' }, 'name length').exec();
  *
  * @param {Object} [conditions]
  * @param {Object|String} [projection] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)