Merge pull request #12162 from hasezoey/jsdocHeaderNewLine

style: change jsdoc headers to have a consistent empty jsdoc line after

lib/document.js

@@ -1687,6 +1687,7 @@ Document.prototype.$__getValue = function(path) {
  * as opposed to a `$set`.
  *
  * #### Example:
+ *
  *     const schema = new Schema({ counter: Number });
  *     const Test = db.model('Test', schema);
  *

lib/error/index.js

@@ -5,6 +5,7 @@
  * Mongoose-specific errors.
  *
  * #### Example:
+ *
  *     const Model = mongoose.model('Test', new mongoose.Schema({ answer: Number }));
  *     const doc = new Model({ answer: 'not a number' });
  *     const err = doc.validateSync();

lib/helpers/populate/markArraySubdocsPopulated.js

@@ -7,6 +7,7 @@ const utils = require('../../utils');
  * subdoc within the array knows its subpaths are populated.
  *
  * #### Example:
+ *
  *     const doc = await Article.findOne().populate('comments.author');
  *     doc.comments[0].populated('author'); // Should be set
  */

lib/helpers/projection/hasIncludedChildren.js

@@ -5,6 +5,7 @@
  * the projection.
  *
  * #### Example:
+ *
  *     const res = hasIncludedChildren({ 'a.b.c': 0 });
  *     res.a; // 1
  *     res['a.b']; // 1

lib/index.js

@@ -51,6 +51,7 @@ const objectIdHexRegexp = /^[0-9A-Fa-f]{24}$/;
  * Most apps will only use this one instance.
  *
  * #### Example:
+ *
  *     const mongoose = require('mongoose');
  *     mongoose instanceof mongoose.Mongoose; // true
  *

lib/model.js

@@ -3698,6 +3698,7 @@ Model.applyDefaults = function applyDefaults(doc) {
  * Cast the given POJO to the model's schema
  *
  * #### Example:
+ *
  *     const Test = mongoose.model('Test', Schema({ num: Number }));
  *
  *     const obj = Test.castObject({ num: '42' });
@@ -3979,6 +3980,7 @@ Model.update = function update(conditions, doc, options, callback) {
  * and `post('updateMany')` instead.
  *
  * #### Example:
+ *
  *     const res = await Person.updateMany({ name: /Stark$/ }, { isDeleted: true });
  *     res.matchedCount; // Number of documents matched
  *     res.modifiedCount; // Number of documents modified
@@ -4019,6 +4021,7 @@ Model.updateMany = function updateMany(conditions, doc, options, callback) {
  * - Use `replaceOne()` if you want to overwrite an entire document rather than using atomic operators like `$set`.
  *
  * #### Example:
+ *
  *     const res = await Person.updateOne({ name: 'Jean-Luc Picard' }, { ship: 'USS Enterprise' });
  *     res.matchedCount; // Number of documents matched
  *     res.modifiedCount; // Number of documents modified
@@ -4056,6 +4059,7 @@ Model.updateOne = function updateOne(conditions, doc, options, callback) {
  * given document (no atomic operators like `$set`).
  *
  * #### Example:
+ *
  *     const res = await Person.replaceOne({ _id: 24601 }, { name: 'Jean Valjean' });
  *     res.matchedCount; // Number of documents matched
  *     res.modifiedCount; // Number of documents modified

lib/options/SchemaNumberOptions.js

@@ -50,6 +50,7 @@ Object.defineProperty(SchemaNumberOptions.prototype, 'max', opts);
  * equal to one of the given values.
  *
  * #### Example:
+ *
  *     const schema = new Schema({
  *       favoritePrime: {
  *         type: Number,
@@ -71,6 +72,7 @@ Object.defineProperty(SchemaNumberOptions.prototype, 'enum', opts);
  * Sets default [populate options](/docs/populate.html#query-conditions).
  *
  * #### Example:
+ *
  *     const schema = new Schema({
  *       child: {
  *         type: Number,

lib/options/SchemaObjectIdOptions.js

@@ -35,6 +35,7 @@ Object.defineProperty(SchemaObjectIdOptions.prototype, 'auto', opts);
  * Sets default [populate options](/docs/populate.html#query-conditions).
  *
  * #### Example:
+ *
  *     const schema = new Schema({
  *       child: {
  *         type: 'ObjectId',

lib/query.js

@@ -262,6 +262,7 @@ Query.prototype.toConstructor = function toConstructor() {
  * Make a copy of this query so you can re-execute it.
  *
  * #### 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
@@ -2100,6 +2101,7 @@ Query.prototype.get = function get(path) {
  * custom errors.
  *
  * #### 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) {
@@ -3297,6 +3299,7 @@ function prepareDiscriminatorCriteria(query) {
  * - `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
+ *
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
@@ -3439,6 +3442,7 @@ Query.prototype._findOneAndUpdate = wrapThunk(function(callback) {
  * - `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
+ *
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
@@ -3526,6 +3530,7 @@ Query.prototype.findOneAndRemove = function(conditions, options, callback) {
  * - `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
+ *
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
@@ -3645,6 +3650,7 @@ Query.prototype._findOneAndDelete = wrapThunk(function(callback) {
  * - `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
+ *
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
@@ -4417,6 +4423,7 @@ Query.prototype.update = function(conditions, doc, options, callback) {
  * and `post('updateMany')` instead.
  *
  * #### Example:
+ *
  *     const res = await Person.updateMany({ name: /Stark$/ }, { isDeleted: true });
  *     res.n; // Number of documents matched
  *     res.nModified; // Number of documents modified
@@ -4482,6 +4489,7 @@ Query.prototype.updateMany = function(conditions, doc, options, callback) {
  * and `post('updateOne')` instead.
  *
  * #### 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
@@ -4545,6 +4553,7 @@ Query.prototype.updateOne = function(conditions, doc, options, callback) {
  * and `post('replaceOne')` instead.
  *
  * #### Example:
+ *
  *     const res = await Person.replaceOne({ _id: 24601 }, { name: 'Jean Valjean' });
  *     res.n; // Number of documents matched
  *     res.nModified; // Number of documents modified
@@ -5128,13 +5137,15 @@ Query.prototype.populate = function() {
  * Gets a list of paths to be populated by this query
  *
  * #### Example:
+ *
  *      bookSchema.pre('findOne', function() {
  *        let keys = this.getPopulatedPaths(); // ['author']
  *      });
  *      ...
  *      Book.findOne({}).populate('author');
  *
  * #### Example:
+ *
  *      // Deep populate
  *      const q = L1.find().populate({
  *        path: 'level2',

lib/schema.js

@@ -1403,6 +1403,7 @@ Schema.prototype.indexedPaths = function indexedPaths() {
  * Given a path, returns whether it is a real, virtual, nested, or ad-hoc/undefined path.
  *
  * #### Example:
+ *
  *     const s = new Schema({ name: String, nested: { foo: String } });
  *     s.virtual('foo').get(() => 42);
  *     s.pathType('name'); // "real"

lib/schema/SubdocumentPath.js

@@ -280,6 +280,7 @@ SubdocumentPath.prototype.doValidateSync = function(value, scope, options) {
  * Adds a discriminator to this single nested subdocument.
  *
  * #### Example:
+ *
  *     const shapeSchema = Schema({ name: String }, { discriminatorKey: 'kind' });
  *     const schema = Schema({ shape: shapeSchema });
  *

lib/schema/documentarray.js

@@ -171,6 +171,7 @@ function _createConstructor(schema, options, baseClass) {
  * Adds a discriminator to this document array.
  *
  * #### Example:
+ *
  *     const shapeSchema = Schema({ name: String }, { discriminatorKey: 'kind' });
  *     const schema = Schema({ shapes: [shapeSchema] });
  *

lib/schema/string.js

@@ -267,6 +267,7 @@ SchemaString.prototype.enum = function() {
  * Note that `lowercase` does **not** affect regular expression queries:
  *
  * #### Example:
+ *
  *     // Still queries for documents whose `email` matches the regular
  *     // expression /SomeEmail/. Mongoose does **not** convert the RegExp
  *     // to lowercase.
@@ -305,6 +306,7 @@ SchemaString.prototype.lowercase = function(shouldApply) {
  * Note that `uppercase` does **not** affect regular expression queries:
  *
  * #### Example:
+ *
  *     // Mongoose does **not** convert the RegExp to uppercase.
  *     M.find({ email: /an example/ });
  *
@@ -347,6 +349,7 @@ SchemaString.prototype.uppercase = function(shouldApply) {
  * Note that `trim` does **not** affect regular expression queries:
  *
  * #### Example:
+ *
  *     // Mongoose does **not** trim whitespace from the RegExp.
  *     M.find({ name: / some name / });
  *

lib/types/buffer.js

@@ -166,6 +166,7 @@ MongooseBuffer.mixin = {
  * Converts this buffer to its Binary type representation.
  *
  * #### SubTypes:
+ *
  *     const bson = require('bson')
  *     bson.BSON_BINARY_SUBTYPE_DEFAULT
  *     bson.BSON_BINARY_SUBTYPE_FUNCTION

lib/types/map.js

@@ -68,6 +68,7 @@ class MongooseMap extends Map {
    * ObjectIds as keys.
    *
    * #### Example:
+   *
    *     doc.myMap.set('test', 42); // works
    *     doc.myMap.set({ obj: 42 }, 42); // Throws "Mongoose maps only support string keys"
    *
@@ -197,6 +198,7 @@ class MongooseMap extends Map {
    * the `flattenMaps` option to convert this map to a POJO instead.
    *
    * #### Example:
+   *
    *     doc.myMap.toJSON() instanceof Map; // true
    *     doc.myMap.toJSON({ flattenMaps: true }) instanceof Map; // false
    *