mongoose 6.2.9 → 6.2.10

package/lib/query.js

@@ -69,7 +69,7 @@ const queryOptionMethods = new Set([
  * to instantiate a `Query` directly. Instead use Model functions like
  * [`Model.find()`](/docs/api.html#find_find).
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = MyModel.find(); // `query` is an instance of `Query`
  *     query.setOptions({ lean : true });
@@ -154,7 +154,9 @@ Query.base = mquery.prototype;
 /**
  * Flag to opt out of using `$geoWithin`.
  *
- *     mongoose.Query.use$geoWithin = false;
+ * ```javascript
+ * mongoose.Query.use$geoWithin = false;
+ * ```
  *
  * MongoDB 2.4 deprecated the use of `$within`, replacing it with `$geoWithin`. Mongoose uses `$geoWithin` by default (which is 100% backward compatible with `$within`). If you are running an older version of MongoDB, set this flag to `false` so your `within()` queries continue to work.
  *
@@ -171,7 +173,7 @@ Query.use$geoWithin = mquery.use$geoWithin;
 /**
  * Converts this query to a customized, reusable query constructor with all arguments and options retained.
  *
- * ####Example
+ * #### Example
  *
  *     // Create a query for adventure movies and read from the primary
  *     // node in the replica-set unless it is down, in which case we'll
@@ -253,7 +255,7 @@ Query.prototype.toConstructor = function toConstructor() {
 /**
  * Make a copy of this query so you can re-execute it.
  *
- * ####Example:
+ * #### Example:
  *     const q = Book.findOne({ title: 'Casino Royale' });
  *     await q.exec();
  *     await q.exec(); // Throws an error because you can't execute a query twice
@@ -301,7 +303,7 @@ Query.prototype.clone = function clone() {
 /**
  * Specifies a javascript function or expression to pass to MongoDBs query system.
  *
- * ####Example
+ * #### Example
  *
  *     query.$where('this.comments.length === 10 || this.name.length === 5')
  *
@@ -311,7 +313,7 @@ Query.prototype.clone = function clone() {
  *       return this.comments.length === 10 || this.name.length === 5;
  *     })
  *
- * ####NOTE:
+ * #### Note:
  *
  * Only use `$where` when you have a condition that cannot be met using other MongoDB operators like `$lt`.
  * **Be sure to read about all of [its caveats](https://docs.mongodb.org/manual/reference/operator/where/) before using.**
@@ -329,7 +331,7 @@ Query.prototype.clone = function clone() {
 /**
  * Specifies a `path` for use with chaining.
  *
- * ####Example
+ * #### Example
  *
  *     // instead of writing:
  *     User.find({age: {$gte: 21, $lte: 65}}, callback);
@@ -359,13 +361,13 @@ Query.prototype.clone = function clone() {
 /**
  * Specifies a `$slice` projection for an array.
  *
- * ####Example
+ * #### Example
  *
- *     query.slice('comments', 5)
- *     query.slice('comments', -5)
- *     query.slice('comments', [10, 5])
- *     query.where('comments').slice(5)
- *     query.where('comments').slice([-10, 5])
+ *     query.slice('comments', 5);
+ *     query.slice('comments', -5);
+ *     query.slice('comments', [10, 5]);
+ *     query.where('comments').slice(5);
+ *     query.where('comments').slice([-10, 5]);
  *
  * @method slice
  * @memberOf Query
@@ -437,7 +439,7 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies the complementary comparison value for paths specified with `where()`
  *
- * ####Example
+ * #### Example
  *
  *     User.where('age').equals(49);
  *
@@ -456,9 +458,9 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies arguments for an `$or` condition.
  *
- * ####Example
+ * #### Example
  *
- *     query.or([{ color: 'red' }, { status: 'emergency' }])
+ *     query.or([{ color: 'red' }, { status: 'emergency' }]);
  *
  * @see $or https://docs.mongodb.org/manual/reference/operator/or/
  * @method or
@@ -472,9 +474,9 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies arguments for a `$nor` condition.
  *
- * ####Example
+ * #### Example
  *
- *     query.nor([{ color: 'green' }, { status: 'ok' }])
+ *     query.nor([{ color: 'green' }, { status: 'ok' }]);
  *
  * @see $nor https://docs.mongodb.org/manual/reference/operator/nor/
  * @method nor
@@ -488,7 +490,7 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies arguments for a `$and` condition.
  *
- * ####Example
+ * #### Example
  *
  *     query.and([{ color: 'green' }, { status: 'ok' }])
  *
@@ -506,12 +508,12 @@ Query.prototype._validateOp = function() {
  *
  * When called with one argument, the most recent path passed to `where()` is used.
  *
- * ####Example
+ * #### Example
  *
- *     Thing.find().where('age').gt(21)
+ *     Thing.find().where('age').gt(21);
  *
  *     // or
- *     Thing.find().gt('age', 21)
+ *     Thing.find().gt('age', 21);
  *
  * @method gt
  * @memberOf Query
@@ -611,7 +613,7 @@ Query.prototype._validateOp = function() {
  *
  * When called with one argument, the most recent path passed to `where()` is used.
  *
- * ####Example:
+ * #### Example:
  *
  *     MyModel.find().where('pets').all(['dog', 'cat', 'ferret']);
  *     // Equivalent:
@@ -631,7 +633,7 @@ Query.prototype._validateOp = function() {
  *
  * When called with one argument, the most recent path passed to `where()` is used.
  *
- * ####Example
+ * #### Example
  *
  *     const docs = await MyModel.where('tags').size(0).exec();
  *     assert(Array.isArray(docs));
@@ -678,7 +680,7 @@ Query.prototype._validateOp = function() {
  * Specifies a `$mod` condition, filters documents for documents whose
  * `path` property is a number that is equal to `remainder` modulo `divisor`.
  *
- * ####Example
+ * #### Example
  *
  *     // All find products whose inventory is odd
  *     Product.find().mod('inventory', [2, 1]);
@@ -724,7 +726,7 @@ Query.prototype.mod = function() {
 /**
  * Specifies an `$exists` condition
  *
- * ####Example
+ * #### Example
  *
  *     // { name: { $exists: true }}
  *     Thing.where('name').exists()
@@ -748,7 +750,7 @@ Query.prototype.mod = function() {
 /**
  * Specifies an `$elemMatch` condition
  *
- * ####Example
+ * #### Example
  *
  *     query.elemMatch('comment', { author: 'autobot', votes: {$gte: 5}})
  *
@@ -777,7 +779,7 @@ Query.prototype.mod = function() {
 /**
  * Defines a `$within` or `$geoWithin` argument for geo-spatial queries.
  *
- * ####Example
+ * #### Example
  *
  *     query.where(path).within().box()
  *     query.where(path).within().circle()
@@ -793,11 +795,11 @@ Query.prototype.mod = function() {
  *
  * **MUST** be used after `where()`.
  *
- * ####NOTE:
+ * #### Note:
  *
  * As of Mongoose 3.7, `$geoWithin` is always used for queries. To change this behavior, see [Query.use$geoWithin](#query_Query-use%2524geoWithin).
  *
- * ####NOTE:
+ * #### Note:
  *
  * In Mongoose 3.7, `within` changed from a getter to a function. If you need the old syntax, use [this](https://github.com/ebensing/mongoose-within).
  *
@@ -816,11 +818,11 @@ Query.prototype.mod = function() {
 /**
  * Specifies the maximum number of documents the query will return.
  *
- * ####Example
+ * #### Example
  *
- *     query.limit(20)
+ *     query.limit(20);
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -849,11 +851,11 @@ Query.prototype.limit = function limit(v) {
 /**
  * Specifies the number of documents to skip.
  *
- * ####Example
+ * #### Example
  *
- *     query.skip(100).limit(20)
+ *     query.skip(100).limit(20);
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -883,11 +885,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies the maxScan option.
  *
- * ####Example
+ * #### Example
  *
- *     query.maxScan(100)
+ *     query.maxScan(100);
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -902,11 +904,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies the batchSize option.
  *
- * ####Example
+ * #### Example
  *
  *     query.batchSize(100)
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -921,11 +923,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies the `comment` option.
  *
- * ####Example
+ * #### Example
  *
  *     query.comment('login query')
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -940,13 +942,13 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies this query as a `snapshot` query.
  *
- * ####Example
+ * #### Example
  *
- *     query.snapshot() // true
- *     query.snapshot(true)
- *     query.snapshot(false)
+ *     query.snapshot(); // true
+ *     query.snapshot(true);
+ *     query.snapshot(false);
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -961,11 +963,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Sets query hints.
  *
- * ####Example
+ * #### Example
  *
- *     query.hint({ indexA: 1, indexB: -1})
+ *     query.hint({ indexA: 1, indexB: -1 });
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -985,7 +987,7 @@ Query.prototype.skip = function skip(v) {
  * Unlike `projection()`, the `select()` function modifies the current
  * projection in place. This function overwrites the existing projection.
  *
- * ####Example:
+ * #### Example:
  *
  *     const q = Model.find();
  *     q.projection(); // null
@@ -1028,7 +1030,7 @@ Query.prototype.projection = function(arg) {
  * either list the fields to include (which excludes all others), or list the fields
  * to exclude (which implies all other fields are included). The [`_id` field is the only exception because MongoDB includes it by default](https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/#suppress-id-field).
  *
- * ####Example
+ * #### Example
  *
  *     // include a and b, exclude other fields
  *     query.select('a b');
@@ -1139,49 +1141,30 @@ Query.prototype.select = function select() {
   throw new TypeError('Invalid select() argument. Must be string or object.');
 };
 
-/**
- * _DEPRECATED_ Sets the slaveOk option.
- *
- * **Deprecated** in MongoDB 2.2 in favor of [read preferences](#query_Query-read).
- *
- * ####Example:
- *
- *     query.slaveOk() // true
- *     query.slaveOk(true)
- *     query.slaveOk(false)
- *
- * @method slaveOk
- * @memberOf Query
- * @instance
- * @deprecated use read() preferences instead if on mongodb >= 2.2
- * @param {Boolean} v defaults to true
- * @see mongodb https://docs.mongodb.org/manual/applications/replication/#read-preference
- * @see slaveOk https://docs.mongodb.org/manual/reference/method/rs.slaveOk/
- * @see read() #query_Query-read
- * @return {Query} this
- * @api public
- */
-
 /**
  * Determines the MongoDB nodes from which to read.
  *
- * ####Preferences:
+ * #### Preferences:
  *
- *     primary - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags.
- *     secondary            Read from secondary if available, otherwise error.
- *     primaryPreferred     Read from primary if available, otherwise a secondary.
- *     secondaryPreferred   Read from a secondary if available, otherwise read from the primary.
- *     nearest              All operations read from among the nearest candidates, but unlike other modes, this option will include both the primary and all secondaries in the random selection.
+ * ```
+ * primary - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags.
+ * secondary            Read from secondary if available, otherwise error.
+ * primaryPreferred     Read from primary if available, otherwise a secondary.
+ * secondaryPreferred   Read from a secondary if available, otherwise read from the primary.
+ * nearest              All operations read from among the nearest candidates, but unlike other modes, this option will include both the primary and all secondaries in the random selection.
+ * ```
  *
  * Aliases
  *
- *     p   primary
- *     pp  primaryPreferred
- *     s   secondary
- *     sp  secondaryPreferred
- *     n   nearest
+ * ```
+ * p   primary
+ * pp  primaryPreferred
+ * s   secondary
+ * sp  secondaryPreferred
+ * n   nearest
+ * ```
  *
- * ####Example:
+ * #### Example:
  *
  *     new Query().read('primary')
  *     new Query().read('p')  // same as primary
@@ -1260,7 +1243,7 @@ Query.prototype.toString = function toString() {
  *
  * Calling `session(null)` removes the session from this query.
  *
- * ####Example:
+ * #### Example:
  *
  *     const s = await mongoose.startSession();
  *     await mongoose.model('Person').findOne({ name: 'Axl Rose' }).session(s);
@@ -1304,7 +1287,7 @@ Query.prototype.session = function session(v) {
  *
  * Defaults to the schema's [`writeConcern` option](/docs/guide.html#writeConcern)
  *
- * ####Example:
+ * #### Example:
  *
  *     // The 'majority' option means the `deleteOne()` promise won't resolve
  *     // until the `deleteOne()` has propagated to the majority of the replica set
@@ -1347,7 +1330,7 @@ Query.prototype.writeConcern = function writeConcern(val) {
  *
  * Defaults to the schema's [`writeConcern.w` option](/docs/guide.html#writeConcern)
  *
- * ####Example:
+ * #### Example:
  *
  *     // The 'majority' option means the `deleteOne()` promise won't resolve
  *     // until the `deleteOne()` has propagated to the majority of the replica set
@@ -1393,7 +1376,7 @@ Query.prototype.w = function w(val) {
  *
  * Defaults to the schema's [`writeConcern.j` option](/docs/guide.html#writeConcern)
  *
- * ####Example:
+ * #### Example:
  *
  *     await mongoose.model('Person').deleteOne({ name: 'Ned Stark' }).j(true);
  *
@@ -1437,7 +1420,7 @@ Query.prototype.j = function j(val) {
  *
  * Defaults to the schema's [`writeConcern.wtimeout` option](/docs/guide.html#writeConcern)
  *
- * ####Example:
+ * #### Example:
  *
  *     // The `deleteOne()` promise won't resolve until this `deleteOne()` has
  *     // propagated to at least `w = 2` members of the replica set. If it takes
@@ -1471,7 +1454,7 @@ Query.prototype.wtimeout = function wtimeout(ms) {
 /**
  * Sets the readConcern option for the query.
  *
- * ####Example:
+ * #### Example:
  *
  *     new Query().readConcern('local')
  *     new Query().readConcern('l')  // same as local
@@ -1489,21 +1472,25 @@ Query.prototype.wtimeout = function wtimeout(ms) {
  *     new Query().readConcern('s')  // same as snapshot
  *
  *
- * ####Read Concern Level:
+ * #### Read Concern Level:
  *
- *     local         MongoDB 3.2+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
- *     available     MongoDB 3.6+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
- *     majority      MongoDB 3.2+ The query returns the data that has been acknowledged by a majority of the replica set members. The documents returned by the read operation are durable, even in the event of failure.
- *     linearizable  MongoDB 3.4+ The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start of the read operation. The query may wait for concurrently executing writes to propagate to a majority of replica set members before returning results.
- *     snapshot      MongoDB 4.0+ Only available for operations within multi-document transactions. Upon transaction commit with write concern "majority", the transaction operations are guaranteed to have read from a snapshot of majority-committed data.
+ * ```
+ * local         MongoDB 3.2+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
+ * available     MongoDB 3.6+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
+ * majority      MongoDB 3.2+ The query returns the data that has been acknowledged by a majority of the replica set members. The documents returned by the read operation are durable, even in the event of failure.
+ * linearizable  MongoDB 3.4+ The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start of the read operation. The query may wait for concurrently executing writes to propagate to a majority of replica set members before returning results.
+ * snapshot      MongoDB 4.0+ Only available for operations within multi-document transactions. Upon transaction commit with write concern "majority", the transaction operations are guaranteed to have read from a snapshot of majority-committed data.
+ * ```
  *
  * Aliases
  *
- *     l   local
- *     a   available
- *     m   majority
- *     lz  linearizable
- *     s   snapshot
+ * ```
+ * l   local
+ * a   available
+ * m   majority
+ * lz  linearizable
+ * s   snapshot
+ * ```
  *
  * Read more about how to use read concern [here](https://docs.mongodb.com/manual/reference/read-concern/).
  *
@@ -1518,11 +1505,11 @@ Query.prototype.wtimeout = function wtimeout(ms) {
 /**
  * Gets query options.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.limit(10);
- *     query.setOptions({ maxTimeMS: 1000 })
+ *     query.setOptions({ maxTimeMS: 1000 });
  *     query.getOptions(); // { limit: 10, maxTimeMS: 1000 }
  *
  * @return {Object} the options
@@ -1536,7 +1523,7 @@ Query.prototype.getOptions = function() {
 /**
  * Sets query options. Some options only make sense for certain operations.
  *
- * ####Options:
+ * #### Options:
  *
  * The following options are only for `find()`:
  *
@@ -1678,7 +1665,7 @@ Query.prototype.setOptions = function(options, overwrite) {
  *
  * Calling `query.explain(v)` is equivalent to `query.setOptions({ explain: v })`
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     const res = await query.find({ a: 1 }).explain('queryPlanner');
@@ -1710,7 +1697,7 @@ Query.prototype.explain = function(verbose) {
  *
  * Calling `query.allowDiskUse(v)` is equivalent to `query.setOptions({ allowDiskUse: v })`
  *
- * ####Example:
+ * #### Example:
  *
  *     await query.find().sort({ name: 1 }).allowDiskUse(true);
  *     // Equivalent:
@@ -1739,7 +1726,7 @@ Query.prototype.allowDiskUse = function(v) {
  *
  * Calling `query.maxTimeMS(v)` is equivalent to `query.setOptions({ maxTimeMS: v })`
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     // Throws an error 'operation exceeded time limit' as long as there's
@@ -1759,7 +1746,7 @@ Query.prototype.maxTimeMS = function(ms) {
 /**
  * Returns the current query filter (also known as conditions) as a [POJO](https://masteringjs.io/tutorials/fundamentals/pojo).
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.find({ a: 1 }).where('b').gt(2);
@@ -1779,7 +1766,7 @@ Query.prototype.getFilter = function() {
  * You should use `getFilter()` instead of `getQuery()` where possible. `getQuery()`
  * will likely be deprecated in a future release.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.find({ a: 1 }).where('b').gt(2);
@@ -1796,7 +1783,7 @@ Query.prototype.getQuery = function() {
 /**
  * Sets the query conditions to the provided JSON object.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.find({ a: 1 })
@@ -1815,7 +1802,7 @@ Query.prototype.setQuery = function(val) {
 /**
  * Returns the current update operations as a JSON object.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.update({}, { $set: { a: 5 } });
@@ -1832,7 +1819,7 @@ Query.prototype.getUpdate = function() {
 /**
  * Sets the current update operation to new value.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.update({}, { $set: { a: 5 } });
@@ -1985,7 +1972,7 @@ Query.prototype._optionsForExec = function(model) {
  * javascript objects, not [Mongoose Documents](/api/document.html). They have no
  * `save` method, getters/setters, virtuals, or other Mongoose features.
  *
- * ####Example:
+ * #### Example:
  *
  *     new Query().lean() // true
  *     new Query().lean(true)
@@ -2020,7 +2007,7 @@ Query.prototype.lean = function(v) {
  * This is useful for query middleware so you can add an update regardless
  * of whether you use `updateOne()`, `updateMany()`, `findOneAndUpdate()`, etc.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Updates `{ $set: { updatedAt: new Date() } }`
  *     new Query().updateOne({}, {}).set('updatedAt', new Date());
@@ -2052,7 +2039,7 @@ Query.prototype.set = function(path, val) {
  * Useful for writing getters/setters that can work with both update operations
  * and `save()`.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = Model.updateOne({}, { $set: { name: 'Jean-Luc Picard' } });
  *     query.get('name'); // 'Jean-Luc Picard'
@@ -2086,7 +2073,7 @@ Query.prototype.get = function get(path) {
  * Gets/sets the error flag on this query. If this flag is not null or
  * undefined, the `exec()` promise will reject without executing.
  *
- * ####Example:
+ * #### Example:
  *
  *     Query().error(); // Get current error value
  *     Query().error(null); // Unset the current error
@@ -2100,7 +2087,7 @@ Query.prototype.get = function get(path) {
  * Note that query casting runs **after** hooks, so cast errors will override
  * custom errors.
  *
- * ####Example:
+ * #### Example:
  *     const TestSchema = new Schema({ num: Number });
  *     const TestModel = db.model('Test', TestSchema);
  *     TestModel.find({ num: 'not a number' }).error(new Error('woops')).exec(function(error) {
@@ -2287,7 +2274,7 @@ Query.prototype._find = wrapThunk(function(callback) {
  * If there are too many documents in the result to fit in memory, use
  * [`Query.prototype.cursor()`](api.html#query_Query-cursor)
  *
- * ####Example
+ * #### Example
  *
  *     // Using async/await
  *     const arr = await Movie.find({ year: { $gte: 1980, $lte: 1989 } });
@@ -2493,7 +2480,7 @@ Query.prototype._findOne = wrapThunk(function(callback) {
  *
  * - `findOne()`
  *
- * ####Example
+ * #### Example
  *
  *     const query  = Kitten.where({ color: 'white' });
  *     query.findOne(function (err, kitten) {
@@ -2644,7 +2631,7 @@ Query.prototype._estimatedDocumentCount = wrapThunk(function(callback) {
  *
  * - `count()`
  *
- * ####Example:
+ * #### Example:
  *
  *     const countQuery = model.where({ 'color': 'black' }).count();
  *
@@ -2701,7 +2688,7 @@ Query.prototype.count = function(filter, callback) {
  *
  * - `estimatedDocumentCount()`
  *
- * ####Example:
+ * #### Example:
  *
  *     await Model.find().estimatedDocumentCount();
  *
@@ -2747,7 +2734,7 @@ Query.prototype.estimatedDocumentCount = function(options, callback) {
  *
  * - `countDocuments()`
  *
- * ####Example:
+ * #### Example:
  *
  *     const countQuery = model.where({ 'color': 'black' }).countDocuments();
  *
@@ -2841,7 +2828,7 @@ Query.prototype.__distinct = wrapThunk(function __distinct(callback) {
  *
  * This function does not trigger any middleware.
  *
- * ####Example
+ * #### Example
  *
  *     distinct(field, conditions, callback)
  *     distinct(field, conditions)
@@ -2902,7 +2889,7 @@ Query.prototype.distinct = function(field, conditions, callback) {
  * sort order of each path is ascending unless the path name is prefixed with `-`
  * which will be treated as descending.
  *
- * ####Example
+ * #### Example
  *
  *     // sort by "field" ascending and "test" descending
  *     query.sort({ field: 'asc', test: -1 });
@@ -2910,7 +2897,7 @@ Query.prototype.distinct = function(field, conditions, callback) {
  *     // equivalent
  *     query.sort('field -test');
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -2935,7 +2922,7 @@ Query.prototype.sort = function(arg) {
  *
  * This function does not trigger any middleware
  *
- * ####Example
+ * #### Example
  *
  *     Character.remove({ name: /Stark/ }, callback);
  *
@@ -2947,13 +2934,13 @@ Query.prototype.sort = function(arg) {
  * - `deletedCount`: the number of documents deleted
  * - `n`: the number of documents deleted. Equal to `deletedCount`.
  *
- * ####Example
+ * #### Example
  *
  *     const res = await Character.remove({ name: /Stark/ });
  *     // Number of docs deleted
  *     res.deletedCount;
  *
- * ####Note
+ * #### Note
  *
  * Calling `remove()` creates a [Mongoose query](./queries.html), and a query
  * does not execute until you either pass a callback, call [`Query#then()`](#query_Query-then),
@@ -3027,7 +3014,7 @@ Query.prototype._remove = wrapThunk(function(callback) {
  *
  * This function triggers `deleteOne` middleware.
  *
- * ####Example
+ * #### Example
  *
  *     await Character.deleteOne({ name: 'Eddard Stark' });
  *
@@ -3042,7 +3029,7 @@ Query.prototype._remove = wrapThunk(function(callback) {
  * - `deletedCount`: the number of documents deleted
  * - `n`: the number of documents deleted. Equal to `deletedCount`.
  *
- * ####Example
+ * #### Example
  *
  *     const res = await Character.deleteOne({ name: 'Eddard Stark' });
  *     // `1` if MongoDB deleted a doc, `0` if no docs matched the filter `{ name: ... }`
@@ -3113,7 +3100,7 @@ Query.prototype._deleteOne = wrapThunk(function(callback) {
  *
  * This function triggers `deleteMany` middleware.
  *
- * ####Example
+ * #### Example
  *
  *     await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });
  *
@@ -3128,7 +3115,7 @@ Query.prototype._deleteOne = wrapThunk(function(callback) {
  * - `deletedCount`: the number of documents deleted
  * - `n`: the number of documents deleted. Equal to `deletedCount`.
  *
- * ####Example
+ * #### Example
  *
  *     const res = await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });
  *     // `0` if no docs matched the filter, number of docs deleted otherwise
@@ -3263,7 +3250,7 @@ function prepareDiscriminatorCriteria(query) {
  *
  * - `findOneAndUpdate()`
  *
- * ####Available options
+ * #### Available options
  *
  * - `new`: bool - if true, return the modified document rather than the original. defaults to false (changed in 4.0)
  * - `upsert`: bool - creates the object if it doesn't exist. defaults to false.
@@ -3274,13 +3261,13 @@ function prepareDiscriminatorCriteria(query) {
  * - `setDefaultsOnInsert`: `true` by default. If `setDefaultsOnInsert` and `upsert` are true, mongoose will apply the [defaults](https://mongoosejs.com/docs/defaults.html) specified in the model's schema if a new document is created.
  * - `rawResult`: if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  *
- * ####Callback Signature
+ * #### Callback Signature
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * ####Examples
+ * #### Examples
  *
  *     query.findOneAndUpdate(conditions, update, options, callback) // executes
  *     query.findOneAndUpdate(conditions, update, options)  // returns Query
@@ -3410,19 +3397,19 @@ Query.prototype._findOneAndUpdate = wrapThunk(function(callback) {
  *
  * - `findOneAndRemove()`
  *
- * ####Available options
+ * #### Available options
  *
  * - `sort`: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
  * - `maxTimeMS`: puts a time limit on the query - requires mongodb >= 2.6.0
  * - `rawResult`: if true, resolves to the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  *
- * ####Callback Signature
+ * #### Callback Signature
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * ####Examples
+ * #### Examples
  *
  *     A.where().findOneAndRemove(conditions, options, callback) // executes
  *     A.where().findOneAndRemove(conditions, options)  // return Query
@@ -3497,19 +3484,19 @@ Query.prototype.findOneAndRemove = function(conditions, options, callback) {
  * this distinction is purely pedantic. You should use `findOneAndDelete()`
  * unless you have a good reason not to.
  *
- * ####Available options
+ * #### Available options
  *
  * - `sort`: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
  * - `maxTimeMS`: puts a time limit on the query - requires mongodb >= 2.6.0
  * - `rawResult`: if true, resolves to the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  *
- * ####Callback Signature
+ * #### Callback Signature
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * ####Examples
+ * #### Examples
  *
  *     A.where().findOneAndDelete(conditions, options, callback) // executes
  *     A.where().findOneAndDelete(conditions, options)  // return Query
@@ -3616,19 +3603,19 @@ Query.prototype._findOneAndDelete = wrapThunk(function(callback) {
  *
  * - `findOneAndReplace()`
  *
- * ####Available options
+ * #### Available options
  *
  * - `sort`: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
  * - `maxTimeMS`: puts a time limit on the query - requires mongodb >= 2.6.0
  * - `rawResult`: if true, resolves to the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  *
- * ####Callback Signature
+ * #### Callback Signature
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * ####Examples
+ * #### Examples
  *
  *     A.where().findOneAndReplace(filter, replacement, options, callback); // executes
  *     A.where().findOneAndReplace(filter, replacement, options); // return Query
@@ -4193,15 +4180,15 @@ Query.prototype._replaceOne = wrapThunk(function(callback) {
  *
  * - `update()`
  *
- * ####Example
+ * #### Example
  *
- *     Model.where({ _id: id }).update({ title: 'words' })
+ *     Model.where({ _id: id }).update({ title: 'words' });
  *
  *     // becomes
  *
- *     Model.where({ _id: id }).update({ $set: { title: 'words' }})
+ *     Model.where({ _id: id }).update({ $set: { title: 'words' }});
  *
- * ####Valid options:
+ * #### Valid options:
  *
  *  - `upsert` (boolean) whether to create the doc if it doesn't match (false)
  *  - `multi` (boolean) whether multiple documents should be updated (false)
@@ -4211,47 +4198,51 @@ Query.prototype._replaceOne = wrapThunk(function(callback) {
  *  - `read`
  *  - `writeConcern`
  *
- * ####Note
+ * #### Note
  *
  * Passing an empty object `{}` as the doc will result in a no-op. The update operation will be ignored and the callback executed without sending the command to MongoDB.
  *
- * ####Note
+ * #### Note
  *
  * The operation is only executed when a callback is passed. To force execution without a callback, we must first call update() and then execute it by using the `exec()` method.
  *
- *     const q = Model.where({ _id: id });
- *     q.update({ $set: { name: 'bob' }}).update(); // not executed
+ * ```javascript
+ * const q = Model.where({ _id: id });
+ * q.update({ $set: { name: 'bob' }}).update(); // not executed
  *
- *     q.update({ $set: { name: 'bob' }}).exec(); // executed
+ * q.update({ $set: { name: 'bob' }}).exec(); // executed
  *
- *     // keys that are not [atomic](https://docs.mongodb.com/manual/tutorial/model-data-for-atomic-operations/#pattern) ops become `$set`.
- *     // this executes the same command as the previous example.
- *     q.update({ name: 'bob' }).exec();
+ * // keys that are not [atomic](https://docs.mongodb.com/manual/tutorial/model-data-for-atomic-operations/#pattern) ops become `$set`.
+ * // this executes the same command as the previous example.
+ * q.update({ name: 'bob' }).exec();
  *
- *     // multi updates
- *     Model.where()
- *          .update({ name: /^match/ }, { $set: { arr: [] }}, { multi: true }, callback)
+ * // multi updates
+ * Model.where()
+ *      .update({ name: /^match/ }, { $set: { arr: [] }}, { multi: true }, callback)
  *
- *     // more multi updates
- *     Model.where()
- *          .setOptions({ multi: true })
- *          .update({ $set: { arr: [] }}, callback)
+ * // more multi updates
+ * Model.where()
+ *      .setOptions({ multi: true })
+ *      .update({ $set: { arr: [] }}, callback)
  *
- *     // single update by default
- *     Model.where({ email: 'address@example.com' })
- *          .update({ $inc: { counter: 1 }}, callback)
+ * // single update by default
+ * Model.where({ email: 'address@example.com' })
+ *      .update({ $inc: { counter: 1 }}, callback)
+ * ```
  *
  * API summary
  *
- *     update(filter, doc, options, cb) // executes
- *     update(filter, doc, options)
- *     update(filter, doc, cb) // executes
- *     update(filter, doc)
- *     update(doc, cb) // executes
- *     update(doc)
- *     update(cb) // executes
- *     update(true) // executes
- *     update()
+ * ```javascript
+ * update(filter, doc, options, cb); // executes
+ * update(filter, doc, options);
+ * update(filter, doc, cb); // executes
+ * update(filter, doc);
+ * update(doc, cb); // executes
+ * update(doc);
+ * update(cb); // executes
+ * update(true); // executes
+ * update();
+ * ```
  *
  * @param {Object} [filter]
  * @param {Object} [doc] the update command
@@ -4308,7 +4299,7 @@ Query.prototype.update = function(conditions, doc, options, callback) {
  * **Note** updateMany will _not_ fire update middleware. Use `pre('updateMany')`
  * and `post('updateMany')` instead.
  *
- * ####Example:
+ * #### Example:
  *     const res = await Person.updateMany({ name: /Stark$/ }, { isDeleted: true });
  *     res.n; // Number of documents matched
  *     res.nModified; // Number of documents modified
@@ -4373,7 +4364,7 @@ Query.prototype.updateMany = function(conditions, doc, options, callback) {
  * **Note** updateOne will _not_ fire update middleware. Use `pre('updateOne')`
  * and `post('updateOne')` instead.
  *
- * ####Example:
+ * #### Example:
  *     const res = await Person.updateOne({ name: 'Jean-Luc Picard' }, { ship: 'USS Enterprise' });
  *     res.n; // Number of documents matched
  *     res.nModified; // Number of documents modified
@@ -4436,7 +4427,7 @@ Query.prototype.updateOne = function(conditions, doc, options, callback) {
  * **Note** replaceOne will _not_ fire update middleware. Use `pre('replaceOne')`
  * and `post('replaceOne')` instead.
  *
- * ####Example:
+ * #### Example:
  *     const res = await Person.replaceOne({ _id: 24601 }, { name: 'Jean Valjean' });
  *     res.n; // Number of documents matched
  *     res.nModified; // Number of documents modified
@@ -4540,7 +4531,7 @@ function _update(query, op, filter, doc, options, callback) {
  *
  * Any functions you pass to `transform()` will run **after** any post hooks.
  *
- * ####Example:
+ * #### Example:
  *
  *     const res = await MyModel.findOne().transform(res => {
  *       // Sets a `loadedAt` property on the doc that tells you the time the
@@ -4567,7 +4558,7 @@ Query.prototype.transform = function(fn) {
  * This is handy for integrating with async/await, because `orFail()` saves you
  * an extra `if` statement to check if no document was found.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Throws if no doc returned
  *     await Model.findOne({ foo: 'bar' }).orFail();
@@ -4657,7 +4648,7 @@ function _orFailError(err, query) {
 /**
  * Executes the query
  *
- * ####Examples:
+ * #### Examples:
  *
  *     const promise = query.exec();
  *     const promise = query.exec('update');
@@ -4797,7 +4788,7 @@ Query.prototype.catch = function(reject) {
  * Add pre [middleware](/docs/middleware.html) to this query instance. Doesn't affect
  * other queries.
  *
- * ####Example:
+ * #### Example:
  *
  *     const q1 = Question.find({ answer: 42 });
  *     q1.pre(function middleware() {
@@ -4823,7 +4814,7 @@ Query.prototype.pre = function(fn) {
  * Add post [middleware](/docs/middleware.html) to this query instance. Doesn't affect
  * other queries.
  *
- * ####Example:
+ * #### Example:
  *
  *     const q1 = Question.find({ answer: 42 });
  *     q1.post(function middleware() {
@@ -4922,7 +4913,7 @@ function castDoc(query, overwrite) {
 /**
  * Specifies paths which should be populated with other documents.
  *
- * ####Example:
+ * #### Example:
  *
  *     let book = await Book.findOne().populate('authors');
  *     book.title; // 'Node.js in Action'
@@ -5029,14 +5020,14 @@ Query.prototype.populate = function() {
 /**
  * Gets a list of paths to be populated by this query
  *
- * ####Example:
+ * #### Example:
  *      bookSchema.pre('findOne', function() {
  *        let keys = this.getPopulatedPaths(); // ['author']
  *      });
  *      ...
  *      Book.findOne({}).populate('author');
  *
- * ####Example:
+ * #### Example:
  *      // Deep populate
  *      const q = L1.find().populate({
  *        path: 'level2',
@@ -5078,7 +5069,7 @@ function _getPopulatedPaths(list, arr, prefix) {
 /**
  * Casts this query to the schema of `model`
  *
- * ####Note
+ * #### Note
  *
  * If `obj` is present, it is cast instead of this query.
  *
@@ -5203,7 +5194,7 @@ Query.prototype._applyPaths = function applyPaths() {
  *
  * The `.cursor()` function triggers pre find hooks, but **not** post find hooks.
  *
- * ####Example
+ * #### Example
  *
  *     // There are 2 ways to use a cursor. First, as a stream:
  *     Thing.
@@ -5227,7 +5218,7 @@ Query.prototype._applyPaths = function applyPaths() {
  *       console.log(doc);
  *     }
  *
- * ####Valid options
+ * #### Valid options
  *
  *   - `transform`: optional function which accepts a mongoose document. The return value of the function will be emitted on `data` and returned by `.next()`.
  *
@@ -5274,7 +5265,7 @@ Query.prototype.maxscan = Query.base.maxScan;
 /**
  * Sets the tailable option (for use with capped collections).
  *
- * ####Example
+ * #### Example
  *
  *     query.tailable(); // true
  *     query.tailable(true);
@@ -5283,7 +5274,7 @@ Query.prototype.maxscan = Query.base.maxScan;
  *     // Set both `tailable` and `awaitData` options
  *     query.tailable({ awaitData: true });
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -5324,23 +5315,23 @@ Query.prototype.tailable = function(val, opts) {
 /**
  * Declares an intersects query for `geometry()`.
  *
- * ####Example
+ * #### Example
  *
  *     query.where('path').intersects().geometry({
- *         type: 'LineString'
- *       , coordinates: [[180.0, 11.0], [180, 9.0]]
- *     })
+ *       type: 'LineString',
+ *       coordinates: [[180.0, 11.0], [180, 9.0]]
+ *     });
  *
  *     query.where('path').intersects({
- *         type: 'LineString'
- *       , coordinates: [[180.0, 11.0], [180, 9.0]]
- *     })
+ *       type: 'LineString',
+ *       coordinates: [[180.0, 11.0], [180, 9.0]]
+ *     });
  *
- * ####NOTE:
+ * #### Note:
  *
  * **MUST** be used after `where()`.
  *
- * ####NOTE:
+ * #### Note:
  *
  * In Mongoose 3.7, `intersects` changed from a getter to a function. If you need the old syntax, use [this](https://github.com/ebensing/mongoose-within).
  *
@@ -5357,7 +5348,7 @@ Query.prototype.tailable = function(val, opts) {
 /**
  * Specifies a `$geometry` condition
  *
- * ####Example
+ * #### Example
  *
  *     const polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]]
  *     query.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA })
@@ -5375,7 +5366,7 @@ Query.prototype.tailable = function(val, opts) {
  *
  * The argument is assigned to the most recent path passed to `where()`.
  *
- * ####NOTE:
+ * #### Note:
  *
  * `geometry()` **must** come after either `intersects()` or `within()`.
  *
@@ -5399,7 +5390,7 @@ Query.prototype.tailable = function(val, opts) {
  *
  * These operators return documents sorted by distance.
  *
- * ####Example
+ * #### Example
  *
  *     query.where('loc').near({ center: [10, 10] });
  *     query.where('loc').near({ center: [10, 10], maxDistance: 5 });
@@ -5482,13 +5473,13 @@ Query.prototype.near = function() {
 /**
  * _DEPRECATED_ Specifies a `$nearSphere` condition
  *
- * ####Example
+ * #### Example
  *
  *     query.where('loc').nearSphere({ center: [10, 10], maxDistance: 5 });
  *
  * **Deprecated.** Use `query.near()` instead with the `spherical` option set to `true`.
  *
- * ####Example
+ * #### Example
  *
  *     query.where('loc').near({ center: [10, 10], spherical: true });
  *
@@ -5511,7 +5502,7 @@ Query.prototype.nearSphere = function() {
  * You do not need to call this function explicitly, the JavaScript runtime
  * will call it for you.
  *
- * ####Example
+ * #### Example
  *
  *     for await (const doc of Model.aggregate([{ $sort: { name: 1 } }])) {
  *       console.log(doc.name);
@@ -5539,10 +5530,10 @@ if (Symbol.asyncIterator != null) {
 /**
  * Specifies a `$polygon` condition
  *
- * ####Example
+ * #### Example
  *
- *     query.where('loc').within().polygon([10,20], [13, 25], [7,15])
- *     query.polygon('loc', [10,20], [13, 25], [7,15])
+ *     query.where('loc').within().polygon([10, 20], [13, 25], [7, 15]);
+ *     query.polygon('loc', [10, 20], [13, 25], [7, 15]);
  *
  * @method polygon
  * @memberOf Query
@@ -5558,7 +5549,7 @@ if (Symbol.asyncIterator != null) {
 /**
  * Specifies a `$box` condition
  *
- * ####Example
+ * #### Example
  *
  *     const lowerLeft = [40.73083, -73.99756]
  *     const upperRight= [40.741404,  -73.988135]
@@ -5595,7 +5586,7 @@ Query.prototype.box = function(ll, ur) {
 /**
  * Specifies a `$center` or `$centerSphere` condition.
  *
- * ####Example
+ * #### Example
  *
  *     const area = { center: [50, 50], radius: 10, unique: true }
  *     query.where('loc').within().circle(area)
@@ -5640,7 +5631,7 @@ Query.prototype.center = Query.base.circle;
  *
  * **Deprecated.** Use [circle](#query_Query-circle) instead.
  *
- * ####Example
+ * #### Example
  *
  *     const area = { center: [50, 50], radius: 10 };
  *     query.where('loc').within().centerSphere(area);
@@ -5679,9 +5670,9 @@ Query.prototype.centerSphere = function() {
 /**
  * Determines if inclusive field selection has been made.
  *
- *     query.selectedInclusively() // false
- *     query.select('name')
- *     query.selectedInclusively() // true
+ *     query.selectedInclusively(); // false
+ *     query.select('name');
+ *     query.selectedInclusively(); // true
  *
  * @method selectedInclusively
  * @memberOf Query
@@ -5697,10 +5688,10 @@ Query.prototype.selectedInclusively = function selectedInclusively() {
 /**
  * Determines if exclusive field selection has been made.
  *
- *     query.selectedExclusively() // false
- *     query.select('-name')
- *     query.selectedExclusively() // true
- *     query.selectedInclusively() // false
+ *     query.selectedExclusively(); // false
+ *     query.select('-name');
+ *     query.selectedExclusively(); // true
+ *     query.selectedInclusively(); // false
  *
  * @method selectedExclusively
  * @memberOf Query