mongoose 6.4.4 → 6.4.7

package/lib/document.js

@@ -193,6 +193,46 @@ function Document(obj, fields, skipId, options) {
   applyQueue(this);
 }
 
+/**
+ * Boolean flag specifying if the document is new. If you create a document
+ * using `new`, this document will be considered "new". `$isNew` is how
+ * Mongoose determines whether `save()` should use `insertOne()` to create
+ * a new document or `updateOne()` to update an existing document.
+ *
+ * #### Example:
+ *
+ *     const user = new User({ name: 'John Smith' });
+ *     user.$isNew; // true
+ *
+ *     await user.save(); // Sends an `insertOne` to MongoDB
+ *
+ * On the other hand, if you load an existing document from the database
+ * using `findOne()` or another [query operation](/docs/queries.html),
+ * `$isNew` will be false.
+ *
+ * #### Example:
+ *
+ *     const user = await User.findOne({ name: 'John Smith' });
+ *     user.$isNew; // false
+ *
+ * For subdocuments, `$isNew` is true if either the parent has `$isNew` set,
+ * or if you create a new subdocument.
+ *
+ * #### Example:
+ *
+ *     // Assume `Group` has a document array `users`
+ *     const group = await Group.findOne();
+ *     group.users[0].$isNew; // false
+ *
+ *     group.users.push({ name: 'John Smith' });
+ *     group.users[1].$isNew; // true
+ *
+ * @api public
+ * @property $isNew
+ * @memberOf Document
+ * @instance
+ */
+
 Object.defineProperty(Document.prototype, 'isNew', {
   get: function() {
     return this.$isNew;
@@ -202,6 +242,15 @@ Object.defineProperty(Document.prototype, 'isNew', {
   }
 });
 
+/**
+ * Hash containing current validation errors.
+ *
+ * @api public
+ * @property errors
+ * @memberOf Document
+ * @instance
+ */
+
 Object.defineProperty(Document.prototype, 'errors', {
   get: function() {
     return this.$errors;
@@ -210,6 +259,7 @@ Object.defineProperty(Document.prototype, 'errors', {
     this.$errors = value;
   }
 });
+
 /*!
  * Document exposes the NodeJS event emitter API, so you can use
  * `on`, `once`, etc.
@@ -298,52 +348,13 @@ Object.defineProperty(Document.prototype, '$locals', {
   }
 });
 
-
-/**
- * Boolean flag specifying if the document is new. If you create a document
- * using `new`, this document will be considered "new". `$isNew` is how
- * Mongoose determines whether `save()` should use `insertOne()` to create
- * a new document or `updateOne()` to update an existing document.
- *
- * #### Example:
- *     const user = new User({ name: 'John Smith' });
- *     user.$isNew; // true
- *
- *     await user.save(); // Sends an `insertOne` to MongoDB
- *
- * On the other hand, if you load an existing document from the database
- * using `findOne()` or another [query operation](/docs/queries.html),
- * `$isNew` will be false.
- *
- * #### Example:
- *     const user = await User.findOne({ name: 'John Smith' });
- *     user.$isNew; // false
- *
- * For subdocuments, `$isNew` is true if either the parent has `$isNew` set,
- * or if you create a new subdocument.
- *
- * #### Example:
- *     // Assume `Group` has a document array `users`
- *     const group = await Group.findOne();
- *     group.users[0].$isNew; // false
- *
- *     group.users.push({ name: 'John Smith' });
- *     group.users[1].$isNew; // true
- *
- * @api public
- * @property $isNew
- * @memberOf Document
- * @instance
- */
-
-Document.prototype.$isNew;
-
 /**
  * Legacy alias for `$isNew`.
  *
  * @api public
  * @property isNew
  * @memberOf Document
+ * @see $isNew #document_Document-$isNew
  * @instance
  */
 
@@ -400,17 +411,6 @@ Document.prototype.id;
 
 Document.prototype.$errors;
 
-/**
- * Hash containing current validation errors.
- *
- * @api public
- * @property errors
- * @memberOf Document
- * @instance
- */
-
-Document.prototype.errors;
-
 /**
  * A string containing the current operation that Mongoose is executing
  * on this document. May be `null`, `'save'`, `'validate'`, or `'remove'`.
@@ -630,6 +630,8 @@ function $applyDefaultsToNested(val, path, doc) {
  * @param {Object} obj
  * @param {Object} [fields]
  * @param {Boolean} [skipId]
+ * @param {Boolean} [exclude]
+ * @param {Object} [hasIncludedChildren]
  * @api private
  * @method $__buildDoc
  * @memberOf Document
@@ -714,6 +716,8 @@ Document.prototype.toBSON = function() {
  * Note that `init` hooks are [synchronous](/docs/middleware.html#synchronous).
  *
  * @param {Object} doc document returned by mongo
+ * @param {Object} [opts]
+ * @param {Function} [fn]
  * @api public
  * @memberOf Document
  * @instance
@@ -734,10 +738,25 @@ Document.prototype.init = function(doc, opts, fn) {
   return this;
 };
 
+/**
+ * Alias for [`.init`](#document_Document-init)
+ *
+ * @api public
+ */
+
 Document.prototype.$init = function() {
   return this.constructor.prototype.init.apply(this, arguments);
 };
 
+/**
+ * Internal "init" function
+ *
+ * @param {Document} doc
+ * @param {Object} [opts]
+ * @returns {Document} this
+ * @api private
+ */
+
 Document.prototype.$__init = function(doc, opts) {
   this.$isNew = false;
   opts = opts || {};
@@ -871,17 +890,17 @@ function init(self, obj, doc, opts, prefix) {
  *
  * #### Example:
  *
- *     weirdCar.update({$inc: {wheels:1}}, { w: 1 }, callback);
+ *     weirdCar.update({ $inc: { wheels:1 } }, { w: 1 }, callback);
  *
  * #### Valid options:
  *
- *  - same as in [Model.update](#model_Model.update)
+ *  - same as in [Model.update](#model_Model-update)
  *
- * @see Model.update #model_Model.update
- * @param {Object} doc
- * @param {Object} options
- * @param {Function} callback
- * @return {Query}
+ * @see Model.update #model_Model-update
+ * @param {...Object} ops
+ * @param {Object} [options]
+ * @param {Function} [callback]
+ * @return {Query} this
  * @api public
  * @memberOf Document
  * @instance
@@ -910,15 +929,15 @@ Document.prototype.update = function update() {
  *
  * #### Valid options:
  *
- *  - same as in [Model.updateOne](#model_Model.updateOne)
+ *  - same as in [Model.updateOne](#model_Model-updateOne)
  *
- * @see Model.updateOne #model_Model.updateOne
+ * @see Model.updateOne #model_Model-updateOne
  * @param {Object} doc
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Object} [options.lean] if truthy, mongoose will return the document as a plain JavaScript object rather than a mongoose document. See [`Query.lean()`](/docs/api.html#query_Query-lean) and the [Mongoose lean tutorial](/docs/tutorials/lean.html).
  * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
- * @param {Function} callback
+ * @param {Function} [callback]
  * @return {Query}
  * @api public
  * @memberOf Document
@@ -952,12 +971,12 @@ Document.prototype.updateOne = function updateOne(doc, options, callback) {
  *
  * #### Valid options:
  *
- *  - same as in [Model.replaceOne](https://mongoosejs.com/docs/api/model.html#model_Model.replaceOne)
+ *  - same as in [Model.replaceOne](https://mongoosejs.com/docs/api/model.html#model_Model-replaceOne)
  *
- * @see Model.replaceOne #model_Model.replaceOne
+ * @see Model.replaceOne #model_Model-replaceOne
  * @param {Object} doc
- * @param {Object} options
- * @param {Function} callback
+ * @param {Object} [options]
+ * @param {Function} [callback]
  * @return {Query}
  * @api public
  * @memberOf Document
@@ -1030,10 +1049,10 @@ Document.prototype.$session = function $session(session) {
  *
  * @param {Object} obj the object to overwrite this document with
  * @method overwrite
- * @name overwrite
  * @memberOf Document
  * @instance
  * @api public
+ * @return {Document} this
  */
 
 Document.prototype.overwrite = function overwrite(obj) {
@@ -1064,8 +1083,8 @@ Document.prototype.overwrite = function overwrite(obj) {
  * @param {Schema|String|Number|Buffer|*} [type] optionally specify a type for "on-the-fly" attributes
  * @param {Object} [options] optionally specify options that modify the behavior of the set
  * @param {Boolean} [options.merge=false] if true, setting a [nested path](/docs/subdocs.html#subdocuments-versus-nested-paths) will merge existing values rather than overwrite the whole object. So `doc.set('nested', { a: 1, b: 2 })` becomes `doc.set('nested.a', 1); doc.set('nested.b', 2);`
+ * @return {Document} this
  * @method $set
- * @name $set
  * @memberOf Document
  * @instance
  * @api public
@@ -1149,8 +1168,8 @@ Document.prototype.$set = function $set(path, val, type, options) {
       }
 
       if (utils.isNonBuiltinObject(valForKey) && pathtype === 'nested') {
-        $applyDefaultsToNested(path[key], prefix + key, this);
         this.$set(prefix + key, path[key], constructing, Object.assign({}, options, { _skipMarkModified: true }));
+        $applyDefaultsToNested(this.$get(prefix + key), prefix + key, this);
         continue;
       } else if (strict) {
         // Don't overwrite defaults with undefined keys (gh-3981) (gh-9039)
@@ -1554,6 +1573,7 @@ function _isManuallyPopulatedArray(val, ref) {
 
 /**
  * Sets the value of a path, or many paths.
+ * Alias for [`.$set`](#document_Document-$set).
  *
  * #### Example:
  *
@@ -1581,6 +1601,7 @@ function _isManuallyPopulatedArray(val, ref) {
  * @param {Any} val the value to set
  * @param {Schema|String|Number|Buffer|*} [type] optionally specify a type for "on-the-fly" attributes
  * @param {Object} [options] optionally specify options that modify the behavior of the set
+ * @return {Document} this
  * @api public
  * @method set
  * @memberOf Document
@@ -1592,6 +1613,14 @@ Document.prototype.set = Document.prototype.$set;
 /**
  * Determine if we should mark this change as modified.
  *
+ * @param {never} pathToMark UNUSED
+ * @param {String|Symbol} path
+ * @param {Object} options
+ * @param {Any} constructing
+ * @param {never} parts UNUSED
+ * @param {Schema} schema
+ * @param {Any} val
+ * @param {Any} priorVal
  * @return {Boolean}
  * @api private
  * @method $__shouldModify
@@ -1652,6 +1681,14 @@ Document.prototype.$__shouldModify = function(pathToMark, path, options, constru
 /**
  * Handles the actual setting of the value and marking the path modified if appropriate.
  *
+ * @param {String} pathToMark
+ * @param {String|Symbol} path
+ * @param {Object} options
+ * @param {Any} constructing
+ * @param {Array} parts
+ * @param {Schema} schema
+ * @param {Any} val
+ * @param {Any} priorVal
  * @api private
  * @method $__set
  * @memberOf Document
@@ -1727,6 +1764,7 @@ Document.prototype.$__set = function(pathToMark, path, options, constructing, pa
  * Gets a raw value from a path (no getters)
  *
  * @param {String} path
+ * @return {Any} Returns the value from the given `path`.
  * @api private
  */
 
@@ -1739,6 +1777,7 @@ Document.prototype.$__getValue = function(path) {
  *
  * @param {String} path
  * @param {Object} value
+ * @return {Document} this
  * @api private
  */
 
@@ -1763,6 +1802,7 @@ Document.prototype.$__setValue = function(path, val) {
  * @param {Object} [options]
  * @param {Boolean} [options.virtuals=false] Apply virtuals before getting this path
  * @param {Boolean} [options.getters=true] If false, skip applying getters and just get the raw value
+ * @return {Any}
  * @api public
  */
 
@@ -1831,10 +1871,12 @@ Document.prototype.get = function(path, type, options) {
 
 Document.prototype[getSymbol] = Document.prototype.get;
 Document.prototype.$get = Document.prototype.get;
+
 /**
  * Returns the schematype for the given `path`.
  *
  * @param {String} path
+ * @return {SchemaPath}
  * @api private
  * @method $__path
  * @memberOf Document
@@ -1924,6 +1966,7 @@ Document.prototype.$ignore = function(path) {
  * because a child of `a` was directly modified.
  *
  * #### Example:
+ *
  *     const schema = new Schema({ foo: String, nested: { bar: String } });
  *     const Model = mongoose.model('Test', schema);
  *     await Model.create({ foo: 'original', nested: { bar: 'original' } });
@@ -1933,7 +1976,7 @@ Document.prototype.$ignore = function(path) {
  *     doc.directModifiedPaths(); // ['nested.bar']
  *     doc.modifiedPaths(); // ['nested', 'nested.bar']
  *
- * @return {Array}
+ * @return {String[]}
  * @api public
  */
 
@@ -1947,6 +1990,7 @@ Document.prototype.directModifiedPaths = function() {
  * [minimize option](/docs/guide.html#minimize).
  *
  * #### Example:
+ *
  *     const schema = new Schema({ nested: { foo: String } });
  *     const Model = mongoose.model('Test', schema);
  *     const doc = new Model({});
@@ -1957,6 +2001,7 @@ Document.prototype.directModifiedPaths = function() {
  *     doc.$isEmpty('nested'); // false
  *     doc.nested.$isEmpty(); // false
  *
+ * @param {String} [path]
  * @memberOf Document
  * @instance
  * @api public
@@ -1989,6 +2034,10 @@ Document.prototype.$isEmpty = function(path) {
   return Object.keys(this.toObject(isEmptyOptions)).length === 0;
 };
 
+/*!
+ * ignore
+ */
+
 function _isEmpty(v) {
   if (v == null) {
     return true;
@@ -2009,7 +2058,7 @@ function _isEmpty(v) {
  *
  * @param {Object} [options]
  * @param {Boolean} [options.includeChildren=false] if true, returns children of modified paths as well. For example, if false, the list of modified paths for `doc.colors = { primary: 'blue' };` will **not** contain `colors.primary`. If true, `modifiedPaths()` will return an array that contains `colors.primary`.
- * @return {Array}
+ * @return {String[]}
  * @api public
  */
 
@@ -2118,6 +2167,14 @@ Document.prototype.isModified = function(paths, modifiedPaths) {
   return this.$__.activePaths.some('modify');
 };
 
+/**
+ * Alias of [`.isModified`](#document_Document-isModified)
+ *
+ * @method $isModified
+ * @memberOf Document
+ * @api public
+ */
+
 Document.prototype.$isModified = Document.prototype.isModified;
 
 Document.prototype[documentIsModified] = Document.prototype.isModified;
@@ -2160,6 +2217,7 @@ Document.prototype.$isDefault = function(path) {
  * Getter/setter, determines whether the document was removed or not.
  *
  * #### Example:
+ *
  *     const product = await product.remove();
  *     product.$isDeleted(); // true
  *     product.remove(); // no-op, doesn't send anything to the db
@@ -2170,7 +2228,7 @@ Document.prototype.$isDefault = function(path) {
  *
  *
  * @param {Boolean} [val] optional, overrides whether mongoose thinks the doc is deleted
- * @return {Boolean} whether mongoose thinks this doc is deleted.
+ * @return {Boolean|Document} whether mongoose thinks this doc is deleted.
  * @method $isDeleted
  * @memberOf Document
  * @instance
@@ -2195,7 +2253,7 @@ Document.prototype.$isDeleted = function(val) {
  *     doc.isDirectModified('documents.0.title') // true
  *     doc.isDirectModified('documents') // false
  *
- * @param {String|String[]} path
+ * @param {String|String[]} [path]
  * @return {Boolean}
  * @api public
  */
@@ -2220,7 +2278,7 @@ Document.prototype.isDirectModified = function(path) {
 /**
  * Checks if `path` is in the `init` state, that is, it was set by `Document#init()` and not modified since.
  *
- * @param {String} path
+ * @param {String} [path]
  * @return {Boolean}
  * @api public
  */
@@ -2404,7 +2462,7 @@ Document.prototype.isDirectSelected = function isDirectSelected(path) {
  * @param {Boolean} [options.validateModifiedOnly=false] if `true` mongoose validates only modified paths.
  * @param {Array|string} [options.pathsToSkip] list of paths to skip. If set, Mongoose will validate every modified path that is not in this list.
  * @param {Function} [callback] optional callback called after validation completes, passing an error if one occurred
- * @return {Promise} Promise
+ * @return {Promise} Returns a Promise if no `callback` is given.
  * @api public
  */
 
@@ -2460,6 +2518,14 @@ Document.prototype.validate = function(pathsToValidate, options, callback) {
   }, this.constructor.events);
 };
 
+/**
+ * Alias of [`.validate`](#document_Document-validate)
+ *
+ * @method $validate
+ * @memberOf Document
+ * @api public
+ */
+
 Document.prototype.$validate = Document.prototype.validate;
 
 /*!
@@ -2854,6 +2920,7 @@ function _handlePathsToValidate(paths, pathsToValidate) {
 /*!
  * ignore
  */
+
 function _handlePathsToSkip(paths, pathsToSkip) {
   pathsToSkip = new Set(pathsToSkip);
   paths = paths.filter(p => !pathsToSkip.has(p));
@@ -2876,7 +2943,7 @@ function _handlePathsToSkip(paths, pathsToSkip) {
  *       // validation passed
  *     }
  *
- * @param {Array|string} pathsToValidate only validate the given paths
+ * @param {Array|string} [pathsToValidate] only validate the given paths
  * @param {Object} [options] options for validation
  * @param {Boolean} [options.validateModifiedOnly=false] If `true`, Mongoose will only validate modified paths, as opposed to modified paths and `required` paths.
  * @param {Array|string} [options.pathsToSkip] list of paths to skip. If set, Mongoose will validate every modified path that is not in this list.
@@ -2985,7 +3052,7 @@ Document.prototype.validateSync = function(pathsToValidate, options) {
  * The `value` argument (if passed) will be available through the `ValidationError.value` property.
  *
  *     doc.invalidate('size', 'must be less than 20', 14);
-
+ *
  *     doc.validate(function (err) {
  *       console.log(err)
  *       // prints
@@ -3001,8 +3068,8 @@ Document.prototype.validateSync = function(pathsToValidate, options) {
  *     })
  *
  * @param {String} path the field to invalidate. For array elements, use the `array.i.field` syntax, where `i` is the 0-based index in the array.
- * @param {String|Error} errorMsg the error which states the reason `path` was invalid
- * @param {Object|String|Number|any} value optional invalid value
+ * @param {String|Error} err the error which states the reason `path` was invalid
+ * @param {Object|String|Number|any} val optional invalid value
  * @param {String} [kind] optional `kind` property for the error
  * @return {ValidationError} the current ValidationError, with all currently invalidated paths
  * @api public
@@ -3138,7 +3205,7 @@ function _checkImmutableSubpaths(subdoc, schematype, priorVal) {
 /**
  * Checks if a path is invalid
  *
- * @param {String|String[]} path the field to check
+ * @param {String|String[]} [path] the field to check. If unset will always return "false"
  * @method $isValid
  * @memberOf Document
  * @instance
@@ -3167,7 +3234,7 @@ Document.prototype.$isValid = function(path) {
  * Resets the internal modified state of this document.
  *
  * @api private
- * @return {Document}
+ * @return {Document} this
  * @method $__reset
  * @memberOf Document
  * @instance
@@ -3279,6 +3346,7 @@ Document.prototype.$__undoReset = function $__undoReset() {
 /**
  * Returns this documents dirty paths / vals.
  *
+ * @return {Array}
  * @api private
  * @method $__dirty
  * @memberOf Document
@@ -3369,6 +3437,7 @@ Document.prototype.$__setSchema = function(schema) {
 /**
  * Get active path that were changed and are arrays
  *
+ * @return {Array}
  * @api private
  * @method $__getArrayPathsToValidate
  * @memberOf Document
@@ -3397,6 +3466,7 @@ Document.prototype.$__getArrayPathsToValidate = function() {
 /**
  * Get all subdocs (by bfs)
  *
+ * @return {Array}
  * @api public
  * @method $getAllSubdocs
  * @memberOf Document
@@ -3492,6 +3562,7 @@ Document.prototype.$__handleReject = function handleReject(err) {
 /**
  * Internal helper for toObject() and toJSON() that doesn't manipulate options
  *
+ * @return {Object}
  * @api private
  * @method $toObject
  * @memberOf Document
@@ -3571,10 +3642,10 @@ Document.prototype.$toObject = function(options, json) {
   options.minimize = _minimize;
 
   cloneOptions._parentOptions = options;
-  cloneOptions._skipSingleNestedGetters = true;
+  cloneOptions._skipSingleNestedGetters = false;
 
   const gettersOptions = Object.assign({}, cloneOptions);
-  gettersOptions._skipSingleNestedGetters = false;
+  gettersOptions._skipSingleNestedGetters = true;
 
   // remember the root transform function
   // to save it from being overwritten by sub-transform functions
@@ -3638,18 +3709,6 @@ Document.prototype.$toObject = function(options, json) {
  *
  * Buffers are converted to instances of [mongodb.Binary](https://mongodb.github.com/node-mongodb-native/api-bson-generated/binary.html) for proper storage.
  *
- * #### Options:
- *
- * - `getters` apply all getters (path and virtual getters), defaults to false
- * - `aliases` apply all aliases if `virtuals=true`, defaults to true
- * - `virtuals` apply virtual getters (can override `getters` option), defaults to false
- * - `minimize` remove empty objects, defaults to true
- * - `transform` a transform function to apply to the resulting document before returning
- * - `depopulate` depopulate any populated paths, replacing them with their original refs, defaults to false
- * - `versionKey` whether to include the version key, defaults to true
- * - `flattenMaps` convert Maps to POJOs. Useful if you want to JSON.stringify() the result of toObject(), defaults to false
- * - `useProjection` set to `true` to omit fields that are excluded in this document's projection. Unless you specified a projection, this will omit any field that has `select: false` in the schema.
- *
  * #### Getters/Virtuals
  *
  * Example of only applying path getters
@@ -3774,7 +3833,7 @@ Document.prototype.$toObject = function(options, json) {
  * @param {Boolean} [options.versionKey=true] if false, exclude the version key (`__v` by default) from the output
  * @param {Boolean} [options.flattenMaps=false] if true, convert Maps to POJOs. Useful if you want to `JSON.stringify()` the result of `toObject()`.
  * @param {Boolean} [options.useProjection=false] - If true, omits fields that are excluded in this document's projection. Unless you specified a projection, this will omit any field that has `select: false` in the schema.
- * @return {Object} js object
+ * @return {Object} js object (not a POJO)
  * @see mongodb.Binary https://mongodb.github.com/node-mongodb-native/api-bson-generated/binary.html
  * @api public
  * @memberOf Document
@@ -4072,6 +4131,7 @@ Document.prototype.ownerDocument = function() {
  * If this document is a subdocument or populated document, returns the document's
  * parent. Returns the original document if there is no parent.
  *
+ * @return {Document}
  * @api public
  * @method parent
  * @memberOf Document
@@ -4086,9 +4146,10 @@ Document.prototype.parent = function() {
 };
 
 /**
- * Alias for `parent()`. If this document is a subdocument or populated
+ * Alias for [`parent()`](#document_Document-parent). If this document is a subdocument or populated
  * document, returns the document's parent. Returns `undefined` otherwise.
  *
+ * @return {Document}
  * @api public
  * @method $parent
  * @memberOf Document
@@ -4100,6 +4161,7 @@ Document.prototype.$parent = Document.prototype.parent;
 /**
  * Helper for console.log
  *
+ * @return {String}
  * @api public
  * @method inspect
  * @memberOf Document
@@ -4135,6 +4197,7 @@ if (inspect.custom) {
 /**
  * Helper for console.log
  *
+ * @return {String}
  * @api public
  * @method toString
  * @memberOf Document
@@ -4156,7 +4219,7 @@ Document.prototype.toString = function() {
  * document has an `_id`, in which case this function falls back to using
  * `deepEqual()`.
  *
- * @param {Document} doc a document to compare
+ * @param {Document} [doc] a document to compare. If falsy, will always return "false".
  * @return {Boolean}
  * @api public
  * @memberOf Document
@@ -4214,10 +4277,10 @@ Document.prototype.equals = function(doc) {
  * @param {Function} [callback] Callback
  * @see population ./populate.html
  * @see Query#select #query_Query-select
- * @see Model.populate #model_Model.populate
+ * @see Model.populate #model_Model-populate
  * @memberOf Document
  * @instance
- * @return {Promise|null}
+ * @return {Promise|null} Returns a Promise if no `callback` is given.
  * @api public
  */
 
@@ -4274,7 +4337,7 @@ Document.prototype.populate = function populate() {
  * Gets all populated documents associated with this document.
  *
  * @api public
- * @return {Array<Document>} array of populated documents. Empty array if there are no populated documents associated with this document.
+ * @return {Document[]} array of populated documents. Empty array if there are no populated documents associated with this document.
  * @memberOf Document
  * @method $getPopulatedDocs
  * @instance
@@ -4310,6 +4373,8 @@ Document.prototype.$getPopulatedDocs = function $getPopulatedDocs() {
  * If the path was not populated, returns `undefined`.
  *
  * @param {String} path
+ * @param {Any} [val]
+ * @param {Object} [options]
  * @return {Array|ObjectId|Number|Buffer|String|undefined}
  * @memberOf Document
  * @instance
@@ -4357,6 +4422,14 @@ Document.prototype.populated = function(path, val, options) {
   return val;
 };
 
+/**
+ * Alias of [`.populated`](#document_Document-populated).
+ *
+ * @method $populated
+ * @memberOf Document
+ * @api public
+ */
+
 Document.prototype.$populated = Document.prototype.populated;
 
 /**
@@ -4370,7 +4443,7 @@ Document.prototype.$populated = Document.prototype.populated;
  *     doc.$assertPopulated('other path'); // throws an error
  *
  *
- * @param {String|String[]} path
+ * @param {String|String[]} paths
  * @return {Document} this
  * @memberOf Document
  * @method $assertPopulated
@@ -4404,7 +4477,7 @@ Document.prototype.$assertPopulated = function $assertPopulated(paths) {
  *
  * If the path was not provided, then all populated fields are returned to their unpopulated state.
  *
- * @param {String} path
+ * @param {String} [path] Specific Path to depopulate. If unset, will depopulate all paths on the Document.
  * @return {Document} this
  * @see Document.populate #document_Document-populate
  * @api public