Merge pull request #12432 from hasezoey/consistentExample

style: change to consistent "Example:" for jsdoc comments

lib/aggregate.js

@@ -126,7 +126,7 @@ Aggregate.prototype.model = function(model) {
 /**
  * Appends new operators to this aggregate pipeline
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.append({ $project: { field: 1 }}, { $limit: 2 });
  *
@@ -157,7 +157,7 @@ Aggregate.prototype.append = function() {
  * Appends a new $addFields operator to this aggregate pipeline.
  * Requires MongoDB v3.4+ to work
  *
- * #### Examples:
+ * #### Example:
   *
  *     // adding new fields based on existing fields
  *     aggregate.addFields({
@@ -188,7 +188,7 @@ Aggregate.prototype.addFields = function(arg) {
  *
  * Mongoose query [selection syntax](#query_Query-select) is also supported.
  *
- * #### Examples:
+ * #### Example:
  *
  *     // include a, include b, exclude _id
  *     aggregate.project("a b -_id");
@@ -243,7 +243,7 @@ Aggregate.prototype.project = function(arg) {
 /**
  * Appends a new custom $group operator to this aggregate pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.group({ _id: "$department" });
  *
@@ -259,7 +259,7 @@ Aggregate.prototype.project = function(arg) {
 /**
  * Appends a new custom $match operator to this aggregate pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.match({ department: { $in: [ "sales", "engineering" ] } });
  *
@@ -275,7 +275,7 @@ Aggregate.prototype.project = function(arg) {
 /**
  * Appends a new $skip operator to this aggregate pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.skip(10);
  *
@@ -291,7 +291,7 @@ Aggregate.prototype.project = function(arg) {
 /**
  * Appends a new $limit operator to this aggregate pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.limit(10);
  *
@@ -308,7 +308,7 @@ Aggregate.prototype.project = function(arg) {
 /**
  * Appends a new $densify operator to this aggregate pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *      aggregate.densify({
  *        field: 'timestamp',
@@ -335,7 +335,7 @@ Aggregate.prototype.project = function(arg) {
  *
  * **MUST** be used as the first operator in the pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.near({
  *       near: [40.724, -73.997],
@@ -380,7 +380,7 @@ Aggregate.prototype.near = function(arg) {
  * Note that the `$unwind` operator requires the path name to start with '$'.
  * Mongoose will prepend '$' if the specified field doesn't start '$'.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.unwind("tags");
  *     aggregate.unwind("a", "b", "c");
@@ -419,7 +419,7 @@ Aggregate.prototype.unwind = function() {
  * If you are passing in a string Mongoose will prepend '$' if the specified field doesn't start '$'.
  * If you are passing in an object the strings in your expression will not be altered.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.replaceRoot("user");
  *
@@ -450,7 +450,7 @@ Aggregate.prototype.replaceRoot = function(newRoot) {
 /**
  * Appends a new $count operator to this aggregate pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.count("userCount");
  *
@@ -471,7 +471,7 @@ Aggregate.prototype.count = function(fieldName) {
  * Note that the `$sortByCount` operator requires the new root to start with '$'.
  * Mongoose will prepend '$' if the specified field name doesn't start with '$'.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.sortByCount('users');
  *     aggregate.sortByCount({ $mergeObjects: [ "$employee", "$business" ] })
@@ -498,7 +498,7 @@ Aggregate.prototype.sortByCount = function(arg) {
 /**
  * Appends new custom $lookup operator to this aggregate pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.lookup({ from: 'users', localField: 'userId', foreignField: '_id', as: 'users' });
  *
@@ -517,7 +517,7 @@ Aggregate.prototype.lookup = function(options) {
  *
  * Note that graphLookup can only consume at most 100MB of memory, and does not allow disk use even if `{ allowDiskUse: true }` is specified.
  *
- * #### Examples:
+ * #### Example:
  *
  *      // Suppose we have a collection of courses, where a document might look like `{ _id: 0, name: 'Calculus', prerequisite: 'Trigonometry'}` and `{ _id: 0, name: 'Trigonometry', prerequisite: 'Algebra' }`
  *      aggregate.graphLookup({ from: 'courses', startWith: '$prerequisite', connectFromField: 'prerequisite', connectToField: 'name', as: 'prerequisites', maxDepth: 3 }) // this will recursively search the 'courses' collection up to 3 prerequisites
@@ -551,7 +551,7 @@ Aggregate.prototype.graphLookup = function(options) {
 /**
  * Appends new custom $sample operator to this aggregate pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.sample(3); // Add a pipeline that picks 3 random documents
  *
@@ -572,7 +572,7 @@ Aggregate.prototype.sample = function(size) {
  *
  * If a string is passed, it must be a space delimited list of path names. The sort order of each path is ascending unless the path name is prefixed with `-` which will be treated as descending.
  *
- * #### Examples:
+ * #### Example:
  *
  *     // these are equivalent
  *     aggregate.sort({ field: 'asc', test: -1 });
@@ -620,7 +620,7 @@ Aggregate.prototype.sort = function(arg) {
 /**
  * Appends new $unionWith operator to this aggregate pipeline.
  *
- * #### Examples:
+ * #### Example:
  *
  *     aggregate.unionWith({ coll: 'users', pipeline: [ { $match: { _id: 1 } } ] });
  *

lib/model.js

@@ -2172,7 +2172,7 @@ Model.deleteMany = function deleteMany(conditions, options, callback) {
  * See our [query casting tutorial](/docs/tutorials/query_casting.html) for
  * more information on how Mongoose casts `filter`.
  *
- * #### Examples:
+ * #### Example:
  *
  *     // find all documents
  *     await MyModel.find({});
@@ -2537,7 +2537,7 @@ Model.$where = function $where() {
  *
  * Finds a matching document, updates it according to the `update` arg, passing any `options`, and returns the found document (if any) to the callback. The query executes if `callback` is passed else a Query object is returned.
  *
- * #### Examples:
+ * #### Example:
  *
  *     A.findOneAndUpdate(conditions, update, options, callback) // executes
  *     A.findOneAndUpdate(conditions, update, options)  // returns Query
@@ -2670,7 +2670,7 @@ function _decorateUpdateWithVersionKey(update, options, versionKey) {
  *
  * - `findOneAndUpdate()`
  *
- * #### Examples:
+ * #### Example:
  *
  *     A.findByIdAndUpdate(id, update, options, callback) // executes
  *     A.findByIdAndUpdate(id, update, options)  // returns Query
@@ -2767,7 +2767,7 @@ Model.findByIdAndUpdate = function(id, update, options, callback) {
  * this distinction is purely pedantic. You should use `findOneAndDelete()`
  * unless you have a good reason not to.
  *
- * #### Examples:
+ * #### Example:
  *
  *     A.findOneAndDelete(conditions, options, callback) // executes
  *     A.findOneAndDelete(conditions, options)  // return Query
@@ -2873,7 +2873,7 @@ Model.findByIdAndDelete = function(id, options, callback) {
  *
  * - `findOneAndReplace()`
  *
- * #### Examples:
+ * #### Example:
  *
  *     A.findOneAndReplace(filter, replacement, options, callback) // executes
  *     A.findOneAndReplace(filter, replacement, options)  // return Query
@@ -2947,7 +2947,7 @@ Model.findOneAndReplace = function(filter, replacement, options, callback) {
  *
  * - `findOneAndRemove()`
  *
- * #### Examples:
+ * #### Example:
  *
  *     A.findOneAndRemove(conditions, options, callback) // executes
  *     A.findOneAndRemove(conditions, options)  // return Query
@@ -3020,7 +3020,7 @@ Model.findOneAndRemove = function(conditions, options, callback) {
  *
  * - `findOneAndRemove()`
  *
- * #### Examples:
+ * #### Example:
  *
  *     A.findByIdAndRemove(id, options, callback) // executes
  *     A.findByIdAndRemove(id, options)  // return Query
@@ -3967,7 +3967,7 @@ Model.hydrate = function(obj, projection, options) {
  *
  * This method is deprecated. See [Deprecation Warnings](../deprecations.html#update) for details.
  *
- * #### Examples:
+ * #### Example:
  *
  *     MyModel.update({ age: { $gt: 18 } }, { oldEnough: true }, fn);
  *
@@ -4524,7 +4524,7 @@ Model.validate = function validate(obj, pathsToValidate, context, callback) {
  * - justOne: optional boolean, if true Mongoose will always set `path` to an array. Inferred from schema by default.
  * - strictPopulate: optional boolean, set to `false` to allow populating paths that aren't in the schema.
  *
- * #### Examples:
+ * #### Example:
  *
  *     const Dog = mongoose.model('Dog', new Schema({ name: String, breed: String }));
  *     const Person = mongoose.model('Person', new Schema({

lib/query.js

@@ -3340,7 +3340,7 @@ function prepareDiscriminatorCriteria(query) {
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * #### Examples:
+ * #### Example:
  *
  *     query.findOneAndUpdate(conditions, update, options, callback) // executes
  *     query.findOneAndUpdate(conditions, update, options)  // returns Query
@@ -3486,7 +3486,7 @@ Query.prototype._findOneAndUpdate = wrapThunk(function(callback) {
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * #### Examples:
+ * #### Example:
  *
  *     A.where().findOneAndRemove(conditions, options, callback) // executes
  *     A.where().findOneAndRemove(conditions, options)  // return Query
@@ -3574,7 +3574,7 @@ Query.prototype.findOneAndRemove = function(conditions, options, callback) {
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * #### Examples:
+ * #### Example:
  *
  *     A.where().findOneAndDelete(conditions, options, callback) // executes
  *     A.where().findOneAndDelete(conditions, options)  // return Query
@@ -3696,7 +3696,7 @@ Query.prototype._findOneAndDelete = wrapThunk(function(callback) {
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * #### Examples:
+ * #### Example:
  *
  *     A.where().findOneAndReplace(filter, replacement, options, callback); // executes
  *     A.where().findOneAndReplace(filter, replacement, options); // return Query
@@ -4863,7 +4863,7 @@ function _orFailError(err, query) {
 /**
  * Executes the query
  *
- * #### Examples:
+ * #### Example:
  *
  *     const promise = query.exec();
  *     const promise = query.exec('update');

lib/schematype.js

@@ -793,7 +793,7 @@ SchemaType.prototype.get = function(fn) {
  *
  * The error message argument is optional. If not passed, the [default generic error message template](#error_messages_MongooseError-messages) will be used.
  *
- * #### Examples:
+ * #### Example:
  *
  *     // make sure every value is equal to "something"
  *     function validator (val) {

lib/types/array/methods/index.js

@@ -557,7 +557,7 @@ const methods = {
    * the provided value to an embedded document and comparing using
    * [the `Document.equals()` function.](/docs/api.html#document_Document-equals)
    *
-   * #### Examples:
+   * #### Example:
    *
    *     doc.array.pull(ObjectId)
    *     doc.array.pull({ _id: 'someId' })