From c60bfb8ce9f7e9523b95f9657a0cd9057083e071 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Fri, 26 Aug 2022 16:08:29 +0200 Subject: [PATCH 1/3] style: rename "@private" to "@api private" --- examples/redis-todo/routers/todoRouter.js | 8 ++++---- examples/redis-todo/routers/userRouter.js | 4 ++-- lib/utils.js | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/examples/redis-todo/routers/todoRouter.js b/examples/redis-todo/routers/todoRouter.js index de2f8c9ea7c..96851c45ebc 100644 --- a/examples/redis-todo/routers/todoRouter.js +++ b/examples/redis-todo/routers/todoRouter.js @@ -5,7 +5,7 @@ const Todo = require('../db/models/todoModel'); const auth = require('../middleware/auth'); const clearCache = require('../middleware/clearCache'); -/* @private +/* @api private * @func: fetch all user todos * @input: user id * @return: todos @@ -19,7 +19,7 @@ Router.get('/all', auth, async function({ userId }, res) { } }); -/* @private +/* @api private * @func: create todo * @input: todo data, userid * @return: todo @@ -38,7 +38,7 @@ Router.post('/create', auth, clearCache, async function({ userId, body }, res) { } }); -/* @private +/* @api private * @func: update todo * @input: todo data, todoId, userid * @return: updated todo @@ -57,7 +57,7 @@ Router.post('/update', auth, async function({ userId, body }, res) { } }); -/* @private +/* @api private * @func: delete todo * @input: todoId, userid */ diff --git a/examples/redis-todo/routers/userRouter.js b/examples/redis-todo/routers/userRouter.js index 750c3d19ff6..23a77477714 100644 --- a/examples/redis-todo/routers/userRouter.js +++ b/examples/redis-todo/routers/userRouter.js @@ -57,7 +57,7 @@ Router.post('/login', async function({ body }, res) { } }); -/* @private +/* @api private * @func: edit user * @input: username, name or password * @return: edited user @@ -82,7 +82,7 @@ Router.post('/update', auth, async function({ userId, body }, res) { } }); -/* @private +/* @api private * @func: delete user */ Router.delete('/delete', auth, async function({ userId }, res) { diff --git a/lib/utils.js b/lib/utils.js index 8ebd81d8835..c166056e156 100644 --- a/lib/utils.js +++ b/lib/utils.js @@ -641,7 +641,7 @@ exports.setValue = function(path, val, obj, map, _copying) { * * @param {Object} o * @return {Array} - * @private + * @api private */ exports.object = {}; @@ -699,7 +699,7 @@ exports.array = {}; * @param {Array} arr * @param {Function} [filter] If passed, will be invoked with each item in the array. If `filter` returns a falsy value, the item will not be included in the results. * @return {Array} - * @private + * @api private */ exports.array.flatten = function flatten(arr, filter, ret) { @@ -779,7 +779,7 @@ exports.isArrayIndex = function(val) { * * @param {Array} arr * @return {Array} - * @private + * @api private */ exports.array.unique = function(arr) { From 7b8a75c155c0f236df91c5f9cde07b64d4dbe08b Mon Sep 17 00:00:00 2001 From: hasezoey Date: Fri, 26 Aug 2022 16:56:44 +0200 Subject: [PATCH 2/3] style: change "/*!" to "/**" with "api private" this makes the all description and types available via jsdoc, but still excluded from the documentation --- lib/aggregate.js | 3 +- lib/cast/boolean.js | 2 +- lib/cast/number.js | 2 +- lib/cast/string.js | 2 +- lib/connection.js | 2 +- lib/cursor/AggregationCursor.js | 17 +- lib/cursor/QueryCursor.js | 17 +- lib/document.js | 20 ++- lib/drivers/browser/objectid.js | 3 +- .../node-mongodb-native/ReadPreference.js | 2 +- lib/drivers/node-mongodb-native/collection.js | 8 +- lib/error/browserMissingSchema.js | 2 +- lib/error/cast.js | 3 +- lib/error/divergentArray.js | 3 +- lib/error/missingSchema.js | 3 +- lib/error/notFound.js | 3 +- lib/error/overwriteModel.js | 3 +- lib/error/validation.js | 16 +- lib/error/validator.js | 12 +- lib/helpers/clone.js | 2 +- lib/helpers/discriminator/getConstructor.js | 3 +- .../discriminator/getDiscriminatorByValue.js | 13 +- .../getSchemaDiscriminatorByValue.js | 13 +- lib/helpers/document/compile.js | 16 +- .../document/getEmbeddedDiscriminatorPath.js | 6 +- lib/helpers/get.js | 3 +- lib/helpers/getConstructorName.js | 3 +- lib/helpers/isBsonType.js | 3 +- lib/helpers/isMongooseObject.js | 4 +- lib/helpers/isObject.js | 2 +- lib/helpers/isSimpleValidator.js | 2 +- lib/helpers/model/applyHooks.js | 4 +- lib/helpers/model/applyMethods.js | 3 +- lib/helpers/model/applyStatics.js | 3 +- lib/helpers/model/castBulkWrite.js | 9 +- lib/helpers/pluralize.js | 2 +- .../populate/assignRawDocsToIdStructure.js | 8 +- lib/helpers/populate/assignVals.js | 17 +- .../populate/createPopulateQueryFilter.js | 10 +- .../populate/getModelsMapForPopulate.js | 4 +- lib/helpers/populate/getSchemaTypes.js | 4 +- .../populate/markArraySubdocsPopulated.js | 6 +- lib/helpers/projection/hasIncludedChildren.js | 5 +- lib/helpers/projection/isPathExcluded.js | 5 +- lib/helpers/projection/isSubpath.js | 3 +- lib/helpers/query/applyQueryMiddleware.js | 5 +- lib/helpers/query/castUpdate.js | 22 ++- lib/helpers/query/completeMany.js | 5 +- .../query/getEmbeddedDiscriminatorPath.js | 8 +- lib/helpers/query/wrapThunk.js | 4 +- lib/helpers/schema/getIndexes.js | 9 +- lib/helpers/schema/getPath.js | 7 +- lib/helpers/schema/idGetter.js | 3 +- lib/index.js | 4 +- lib/model.js | 84 +++++++--- lib/query.js | 153 ++++++++++++++---- lib/queryhelpers.js | 8 +- lib/schema.js | 14 +- lib/schema/SubdocumentPath.js | 2 +- lib/schema/array.js | 2 +- lib/schema/date.js | 3 +- lib/schema/documentarray.js | 5 +- lib/schema/operators/helpers.js | 4 +- lib/schema/operators/text.js | 2 +- lib/schematype.js | 21 ++- lib/statemachine.js | 25 +-- lib/types/ArraySubdocument.js | 16 +- lib/types/DocumentArray/methods/index.js | 10 +- lib/types/map.js | 4 +- lib/types/objectid.js | 4 +- lib/types/subdocument.js | 38 ++++- lib/utils.js | 83 ++++++---- test/common.js | 4 +- test/util.js | 4 +- 74 files changed, 587 insertions(+), 242 deletions(-) diff --git a/lib/aggregate.js b/lib/aggregate.js index a4cf2ac339b..4fa36f333df 100644 --- a/lib/aggregate.js +++ b/lib/aggregate.js @@ -1104,12 +1104,13 @@ function isOperator(obj) { return k.length === 1 && k[0][0] === '$'; } -/*! +/** * Adds the appropriate `$match` pipeline step to the top of an aggregate's * pipeline, should it's model is a non-root discriminator type. This is * analogous to the `prepareDiscriminatorCriteria` function in `lib/query.js`. * * @param {Aggregate} aggregate Aggregate to prepare + * @api private */ Aggregate._prepareDiscriminatorPipeline = prepareDiscriminatorPipeline; diff --git a/lib/cast/boolean.js b/lib/cast/boolean.js index 92551d41e3e..aaa1fb066b6 100644 --- a/lib/cast/boolean.js +++ b/lib/cast/boolean.js @@ -2,7 +2,7 @@ const CastError = require('../error/cast'); -/*! +/** * Given a value, cast it to a boolean, or throw a `CastError` if the value * cannot be casted. `null` and `undefined` are considered valid. * diff --git a/lib/cast/number.js b/lib/cast/number.js index c96782a38ba..cf0362de186 100644 --- a/lib/cast/number.js +++ b/lib/cast/number.js @@ -2,7 +2,7 @@ const assert = require('assert'); -/*! +/** * Given a value, cast it to a number, or throw an `Error` if the value * cannot be casted. `null` and `undefined` are considered valid. * diff --git a/lib/cast/string.js b/lib/cast/string.js index 4d89f8e2b74..aabb822c5e3 100644 --- a/lib/cast/string.js +++ b/lib/cast/string.js @@ -2,7 +2,7 @@ const CastError = require('../error/cast'); -/*! +/** * Given a value, cast it to a string, or throw a `CastError` if the value * cannot be casted. `null` and `undefined` are considered valid. * diff --git a/lib/connection.js b/lib/connection.js index 2f847bffc2f..682bcd3d34f 100644 --- a/lib/connection.js +++ b/lib/connection.js @@ -26,7 +26,7 @@ const processConnectionOptions = require('./helpers/processConnectionOptions'); const arrayAtomicsSymbol = require('./helpers/symbols').arrayAtomicsSymbol; const sessionNewDocuments = require('./helpers/symbols').sessionNewDocuments; -/*! +/** * A list of authentication mechanisms that don't require a password for authentication. * This is used by the authMechanismDoesNotRequirePassword method. * diff --git a/lib/cursor/AggregationCursor.js b/lib/cursor/AggregationCursor.js index 587dbffdee5..3c8f5c0c48d 100644 --- a/lib/cursor/AggregationCursor.js +++ b/lib/cursor/AggregationCursor.js @@ -71,8 +71,12 @@ function _init(model, c, agg) { } } -/*! +/** * Necessary to satisfy the Readable API + * @method _read + * @memberOf AggregationCursor + * @instance + * @api private */ AggregationCursor.prototype._read = function() { @@ -147,8 +151,12 @@ Object.defineProperty(AggregationCursor.prototype, 'map', { writable: true }); -/*! +/** * Marks this cursor as errored + * @method _markError + * @instance + * @memberOf AggregationCursor + * @api private */ AggregationCursor.prototype._markError = function(error) { @@ -324,9 +332,12 @@ function _waitForCursor(ctx, cb) { }); } -/*! +/** * Get the next doc from the underlying cursor and mongooseify it * (populate, etc.) + * @param {Any} ctx + * @param {Function} cb + * @api private */ function _next(ctx, cb) { diff --git a/lib/cursor/QueryCursor.js b/lib/cursor/QueryCursor.js index baa7710b107..123fdb8f4cc 100644 --- a/lib/cursor/QueryCursor.js +++ b/lib/cursor/QueryCursor.js @@ -85,8 +85,12 @@ function QueryCursor(query, options) { util.inherits(QueryCursor, Readable); -/*! +/** * Necessary to satisfy the Readable API + * @method _read + * @memberOf QueryCursor + * @instance + * @api private */ QueryCursor.prototype._read = function() { @@ -152,8 +156,12 @@ Object.defineProperty(QueryCursor.prototype, 'map', { writable: true }); -/*! +/** * Marks this cursor as errored + * @method _markError + * @memberOf QueryCursor + * @instance + * @api private */ QueryCursor.prototype._markError = function(error) { @@ -340,9 +348,12 @@ function _transformForAsyncIterator(doc) { return doc == null ? { done: true } : { value: doc, done: false }; } -/*! +/** * Get the next doc from the underlying cursor and mongooseify it * (populate, etc.) + * @param {Any} ctx + * @param {Function} cb + * @api private */ function _next(ctx, cb) { diff --git a/lib/document.js b/lib/document.js index 87e491bd52c..dc8cb2bc989 100644 --- a/lib/document.js +++ b/lib/document.js @@ -696,12 +696,15 @@ Document.prototype.$__init = function(doc, opts) { return this; }; -/*! +/** * Init helper. * * @param {Object} self document instance * @param {Object} obj raw mongodb doc * @param {Object} doc object we are initializing + * @param {Object} [opts] Optional Options + * @param {Boolean} [opts.setters] Call `applySetters` instead of `cast` + * @param {String} [prefix] Prefix to add to each path * @api private */ @@ -3815,11 +3818,12 @@ Document.prototype.toObject = function(options) { return this.$toObject(options); }; -/*! +/** * Minimizes an object, removing undefined values and empty objects * * @param {Object} object to minimize * @return {Object} + * @api private */ function minimize(obj) { @@ -3925,12 +3929,14 @@ function applyVirtuals(self, json, options, toObjectOptions) { } -/*! +/** * Applies virtuals properties to `json`. * * @param {Document} self * @param {Object} json + * @param {Object} [options] * @return {Object} `json` + * @api private */ function applyGetters(self, json, options) { @@ -3980,12 +3986,13 @@ function applyGetters(self, json, options) { return json; } -/*! +/** * Applies schema type transforms to `json`. * * @param {Document} self * @param {Object} json * @return {Object} `json` + * @api private */ function applySchemaTypeTransforms(self, json) { @@ -4158,10 +4165,7 @@ Document.prototype.inspect = function(options) { }; if (inspect.custom) { - /*! - * Avoid Node deprecation warning DEP0079 - */ - + // Avoid Node deprecation warning DEP0079 Document.prototype[inspect.custom] = Document.prototype.inspect; } diff --git a/lib/drivers/browser/objectid.js b/lib/drivers/browser/objectid.js index b1e603d714e..d847afe3b8e 100644 --- a/lib/drivers/browser/objectid.js +++ b/lib/drivers/browser/objectid.js @@ -9,8 +9,9 @@ const ObjectId = require('bson').ObjectID; -/*! +/** * Getter for convenience with populate, see gh-6115 + * @api private */ Object.defineProperty(ObjectId.prototype, '_id', { diff --git a/lib/drivers/node-mongodb-native/ReadPreference.js b/lib/drivers/node-mongodb-native/ReadPreference.js index 024ee181a55..bb999ebd684 100644 --- a/lib/drivers/node-mongodb-native/ReadPreference.js +++ b/lib/drivers/node-mongodb-native/ReadPreference.js @@ -7,7 +7,7 @@ const mongodb = require('mongodb'); const ReadPref = mongodb.ReadPreference; -/*! +/** * Converts arguments to ReadPrefs the driver * can understand. * diff --git a/lib/drivers/node-mongodb-native/collection.js b/lib/drivers/node-mongodb-native/collection.js index b390fa1f349..67f3ea06a63 100644 --- a/lib/drivers/node-mongodb-native/collection.js +++ b/lib/drivers/node-mongodb-native/collection.js @@ -66,8 +66,10 @@ NativeCollection.prototype.onClose = function(force) { const syncCollectionMethods = { watch: true, find: true, aggregate: true }; -/*! +/** * Copy the collection methods and make them subject to queues + * @param {Number|String} I + * @api private */ function iter(i) { @@ -296,8 +298,10 @@ NativeCollection.prototype.$format = function(arg, color, shell) { return format(arg, false, color, shell); }; -/*! +/** * Debug print helper + * @param {Any} representation + * @api private */ function inspectable(representation) { diff --git a/lib/error/browserMissingSchema.js b/lib/error/browserMissingSchema.js index fe492d53ccc..3f271499d4d 100644 --- a/lib/error/browserMissingSchema.js +++ b/lib/error/browserMissingSchema.js @@ -8,7 +8,7 @@ const MongooseError = require('./'); class MissingSchemaError extends MongooseError { - /*! + /** * MissingSchema Error constructor. */ constructor() { diff --git a/lib/error/cast.js b/lib/error/cast.js index d3eb0ec32f0..c42e8216691 100644 --- a/lib/error/cast.js +++ b/lib/error/cast.js @@ -56,9 +56,10 @@ class CastError extends MongooseError { this.valueType = getValueType(value); } - /*! + /** * ignore * @param {Readonly} other + * @api private */ copy(other) { this.messageFormat = other.messageFormat; diff --git a/lib/error/divergentArray.js b/lib/error/divergentArray.js index ed86caf1731..7a8d1da5d34 100644 --- a/lib/error/divergentArray.js +++ b/lib/error/divergentArray.js @@ -8,9 +8,10 @@ const MongooseError = require('./'); class DivergentArrayError extends MongooseError { - /*! + /** * DivergentArrayError constructor. * @param {Array} paths + * @api private */ constructor(paths) { const msg = 'For your own good, using `document.save()` to update an array ' diff --git a/lib/error/missingSchema.js b/lib/error/missingSchema.js index ca306b7e611..50c81054a90 100644 --- a/lib/error/missingSchema.js +++ b/lib/error/missingSchema.js @@ -8,9 +8,10 @@ const MongooseError = require('./'); class MissingSchemaError extends MongooseError { - /*! + /** * MissingSchema Error constructor. * @param {String} name + * @api private */ constructor(name) { const msg = 'Schema hasn\'t been registered for model "' + name + '".\n' diff --git a/lib/error/notFound.js b/lib/error/notFound.js index 0e8386b8a25..e1064bb89d9 100644 --- a/lib/error/notFound.js +++ b/lib/error/notFound.js @@ -8,8 +8,9 @@ const MongooseError = require('./'); const util = require('util'); class DocumentNotFoundError extends MongooseError { - /*! + /** * OverwriteModel Error constructor. + * @api private */ constructor(filter, model, numAffected, result) { let msg; diff --git a/lib/error/overwriteModel.js b/lib/error/overwriteModel.js index d509e19551e..1ff180b0498 100644 --- a/lib/error/overwriteModel.js +++ b/lib/error/overwriteModel.js @@ -9,9 +9,10 @@ const MongooseError = require('./'); class OverwriteModelError extends MongooseError { - /*! + /** * OverwriteModel Error constructor. * @param {String} name + * @api private */ constructor(name) { super('Cannot overwrite `' + name + '` model once compiled.'); diff --git a/lib/error/validation.js b/lib/error/validation.js index a3a830825bc..1c3e8639a83 100644 --- a/lib/error/validation.js +++ b/lib/error/validation.js @@ -41,15 +41,19 @@ class ValidationError extends MongooseError { return this.name + ': ' + _generateMessage(this); } - /*! + /** * inspect helper + * @api private */ inspect() { return Object.assign(new Error(this.message), this); } - /*! + /** * add message + * @param {String} path + * @param {String|Error} error + * @api private */ addError(path, error) { if (error instanceof ValidationError) { @@ -68,16 +72,14 @@ class ValidationError extends MongooseError { if (util.inspect.custom) { - /*! - * Avoid Node deprecation warning DEP0079 - */ - + // Avoid Node deprecation warning DEP0079 ValidationError.prototype[util.inspect.custom] = ValidationError.prototype.inspect; } -/*! +/** * Helper for JSON.stringify * Ensure `name` and `message` show up in toJSON output re: gh-9847 + * @api private */ Object.defineProperty(ValidationError.prototype, 'toJSON', { enumerable: false, diff --git a/lib/error/validator.js b/lib/error/validator.js index f880e2b5820..6d54fe7f4f7 100644 --- a/lib/error/validator.js +++ b/lib/error/validator.js @@ -31,16 +31,18 @@ class ValidatorError extends MongooseError { this.reason = properties.reason; } - /*! + /** * toString helper * TODO remove? This defaults to `${this.name}: ${this.message}` + * @api private */ toString() { return this.message; } - /*! + /** * Ensure `name` and `message` show up in toJSON output re: gh-9296 + * @api private */ toJSON() { @@ -53,9 +55,10 @@ Object.defineProperty(ValidatorError.prototype, 'name', { value: 'ValidatorError' }); -/*! +/** * The object used to define this validator. Not enumerable to hide * it from `require('util').inspect()` output re: gh-3925 + * @api private */ Object.defineProperty(ValidatorError.prototype, 'properties', { @@ -67,8 +70,9 @@ Object.defineProperty(ValidatorError.prototype, 'properties', { // Exposed for testing ValidatorError.prototype.formatMessage = formatMessage; -/*! +/** * Formats error messages + * @api private */ function formatMessage(msg, properties) { diff --git a/lib/helpers/clone.js b/lib/helpers/clone.js index 379a74abeca..f7ee5d8d2a8 100644 --- a/lib/helpers/clone.js +++ b/lib/helpers/clone.js @@ -12,7 +12,7 @@ const trustedSymbol = require('./query/trusted').trustedSymbol; const utils = require('../utils'); -/*! +/** * Object clone with Mongoose natives support. * * If options.minimize is true, creates a minimal data object. Empty objects and undefined values will not be cloned. This makes the data payload sent to MongoDB as small as possible. diff --git a/lib/helpers/discriminator/getConstructor.js b/lib/helpers/discriminator/getConstructor.js index ed35b16b33a..7a821c5c99f 100644 --- a/lib/helpers/discriminator/getConstructor.js +++ b/lib/helpers/discriminator/getConstructor.js @@ -2,8 +2,9 @@ const getDiscriminatorByValue = require('./getDiscriminatorByValue'); -/*! +/** * Find the correct constructor, taking into account discriminators + * @api private */ module.exports = function getConstructor(Constructor, value) { diff --git a/lib/helpers/discriminator/getDiscriminatorByValue.js b/lib/helpers/discriminator/getDiscriminatorByValue.js index b2fa010dace..af7605b39d4 100644 --- a/lib/helpers/discriminator/getDiscriminatorByValue.js +++ b/lib/helpers/discriminator/getDiscriminatorByValue.js @@ -2,12 +2,13 @@ const areDiscriminatorValuesEqual = require('./areDiscriminatorValuesEqual'); -/*! -* returns discriminator by discriminatorMapping.value -* -* @param {Model} model -* @param {string} value -*/ +/** + * returns discriminator by discriminatorMapping.value + * + * @param {Object} discriminators + * @param {string} value + * @api private + */ module.exports = function getDiscriminatorByValue(discriminators, value) { if (discriminators == null) { diff --git a/lib/helpers/discriminator/getSchemaDiscriminatorByValue.js b/lib/helpers/discriminator/getSchemaDiscriminatorByValue.js index d4858ef18ad..a04e17c1b1b 100644 --- a/lib/helpers/discriminator/getSchemaDiscriminatorByValue.js +++ b/lib/helpers/discriminator/getSchemaDiscriminatorByValue.js @@ -2,12 +2,13 @@ const areDiscriminatorValuesEqual = require('./areDiscriminatorValuesEqual'); -/*! -* returns discriminator by discriminatorMapping.value -* -* @param {Schema} schema -* @param {string} value -*/ +/** + * returns discriminator by discriminatorMapping.value + * + * @param {Schema} schema + * @param {string} value + * @api private + */ module.exports = function getSchemaDiscriminatorByValue(schema, value) { if (schema == null || schema.discriminators == null) { diff --git a/lib/helpers/document/compile.js b/lib/helpers/document/compile.js index 71597582535..3e5a092cee4 100644 --- a/lib/helpers/document/compile.js +++ b/lib/helpers/document/compile.js @@ -24,8 +24,13 @@ const _isEmptyOptions = Object.freeze({ transform: false }); -/*! +/** * Compiles schemas. + * @param {Object} tree + * @param {Any} proto + * @param {String} prefix + * @param {Object} options + * @api private */ function compile(tree, proto, prefix, options) { @@ -44,8 +49,15 @@ function compile(tree, proto, prefix, options) { } } -/*! +/** * Defines the accessor named prop on the incoming prototype. + * @param {Object} options + * @param {String} options.prop + * @param {Boolean} options.subprops + * @param {Any} options.prototype + * @param {String} [options.prefix] + * @param {Object} options.options + * @api private */ function defineKey({ prop, subprops, prototype, prefix, options }) { diff --git a/lib/helpers/document/getEmbeddedDiscriminatorPath.js b/lib/helpers/document/getEmbeddedDiscriminatorPath.js index 3f4d22a216b..ecbedabc3fa 100644 --- a/lib/helpers/document/getEmbeddedDiscriminatorPath.js +++ b/lib/helpers/document/getEmbeddedDiscriminatorPath.js @@ -3,9 +3,13 @@ const get = require('../get'); const getSchemaDiscriminatorByValue = require('../discriminator/getSchemaDiscriminatorByValue'); -/*! +/** * Like `schema.path()`, except with a document, because impossible to * determine path type without knowing the embedded discriminator key. + * @param {Document} doc + * @param {String} path + * @param {Object} [options] + * @api private */ module.exports = function getEmbeddedDiscriminatorPath(doc, path, options) { diff --git a/lib/helpers/get.js b/lib/helpers/get.js index e23fc1a6c7f..08c2b849fcd 100644 --- a/lib/helpers/get.js +++ b/lib/helpers/get.js @@ -1,8 +1,9 @@ 'use strict'; -/*! +/** * Simplified lodash.get to work around the annoying null quirk. See: * https://github.com/lodash/lodash/issues/3659 + * @api private */ module.exports = function get(obj, path, def) { diff --git a/lib/helpers/getConstructorName.js b/lib/helpers/getConstructorName.js index 10be6b4b47e..5ebe7bb029b 100644 --- a/lib/helpers/getConstructorName.js +++ b/lib/helpers/getConstructorName.js @@ -1,7 +1,8 @@ 'use strict'; -/*! +/** * If `val` is an object, returns constructor name, if possible. Otherwise returns undefined. + * @api private */ module.exports = function getConstructorName(val) { diff --git a/lib/helpers/isBsonType.js b/lib/helpers/isBsonType.js index 54791cd02dc..f75fd40169d 100644 --- a/lib/helpers/isBsonType.js +++ b/lib/helpers/isBsonType.js @@ -1,7 +1,8 @@ 'use strict'; -/*! +/** * Get the bson type, if it exists + * @api private */ function isBsonType(obj, typename) { diff --git a/lib/helpers/isMongooseObject.js b/lib/helpers/isMongooseObject.js index b7157c91ff8..736d0ecd7f4 100644 --- a/lib/helpers/isMongooseObject.js +++ b/lib/helpers/isMongooseObject.js @@ -1,12 +1,12 @@ 'use strict'; const isMongooseArray = require('../types/array/isMongooseArray').isMongooseArray; -/*! +/** * Returns if `v` is a mongoose object that has a `toObject()` method we can use. * * This is for compatibility with libs like Date.js which do foolish things to Natives. * - * @param {any} v + * @param {Any} v * @api private */ diff --git a/lib/helpers/isObject.js b/lib/helpers/isObject.js index cb6f5369a62..21900deded4 100644 --- a/lib/helpers/isObject.js +++ b/lib/helpers/isObject.js @@ -1,6 +1,6 @@ 'use strict'; -/*! +/** * Determines if `arg` is an object. * * @param {Object|Array|String|Function|RegExp|any} arg diff --git a/lib/helpers/isSimpleValidator.js b/lib/helpers/isSimpleValidator.js index dad6c31d681..92c9346822a 100644 --- a/lib/helpers/isSimpleValidator.js +++ b/lib/helpers/isSimpleValidator.js @@ -1,6 +1,6 @@ 'use strict'; -/*! +/** * Determines if `arg` is a flat object. * * @param {Object|Array|String|Function|RegExp|any} arg diff --git a/lib/helpers/model/applyHooks.js b/lib/helpers/model/applyHooks.js index bce1a24ffe9..82a72f26222 100644 --- a/lib/helpers/model/applyHooks.js +++ b/lib/helpers/model/applyHooks.js @@ -22,11 +22,13 @@ applyHooks.middlewareFunctions = [ 'init' ]; -/*! +/** * Register hooks for this model * * @param {Model} model * @param {Schema} schema + * @param {Object} options + * @api private */ function applyHooks(model, schema, options) { diff --git a/lib/helpers/model/applyMethods.js b/lib/helpers/model/applyMethods.js index bd3718da3c8..db6c2a2c2d0 100644 --- a/lib/helpers/model/applyMethods.js +++ b/lib/helpers/model/applyMethods.js @@ -3,11 +3,12 @@ const get = require('../get'); const utils = require('../../utils'); -/*! +/** * Register methods for this model * * @param {Model} model * @param {Schema} schema + * @api private */ module.exports = function applyMethods(model, schema) { diff --git a/lib/helpers/model/applyStatics.js b/lib/helpers/model/applyStatics.js index 3b9501e0428..d94d91c7cfe 100644 --- a/lib/helpers/model/applyStatics.js +++ b/lib/helpers/model/applyStatics.js @@ -1,9 +1,10 @@ 'use strict'; -/*! +/** * Register statics for this model * @param {Model} model * @param {Schema} schema + * @api private */ module.exports = function applyStatics(model, schema) { for (const i in schema.statics) { diff --git a/lib/helpers/model/castBulkWrite.js b/lib/helpers/model/castBulkWrite.js index 27723faa6e7..b58f166d0bb 100644 --- a/lib/helpers/model/castBulkWrite.js +++ b/lib/helpers/model/castBulkWrite.js @@ -7,9 +7,13 @@ const cast = require('../../cast'); const castUpdate = require('../query/castUpdate'); const setDefaultsOnInsert = require('../setDefaultsOnInsert'); -/*! +/** * Given a model and a bulkWrite op, return a thunk that handles casting and * validating the individual op. + * @param {Model} originalModel + * @param {Object} op + * @param {Object} [options] + * @api private */ module.exports = function castBulkWrite(originalModel, op, options) { @@ -222,8 +226,9 @@ function _addDiscriminatorToObject(schema, obj) { } } -/*! +/** * gets discriminator model if discriminator key is present in object + * @api private */ function decideModelByObject(model, object) { diff --git a/lib/helpers/pluralize.js b/lib/helpers/pluralize.js index 7403bbe69c3..657c87f03a8 100644 --- a/lib/helpers/pluralize.js +++ b/lib/helpers/pluralize.js @@ -71,7 +71,7 @@ exports.uncountables = [ ]; const uncountables = exports.uncountables; -/*! +/** * Pluralize function. * * @author TJ Holowaychuk (extracted from _ext.js_) diff --git a/lib/helpers/populate/assignRawDocsToIdStructure.js b/lib/helpers/populate/assignRawDocsToIdStructure.js index 6b45519731d..a4d5f137c39 100644 --- a/lib/helpers/populate/assignRawDocsToIdStructure.js +++ b/lib/helpers/populate/assignRawDocsToIdStructure.js @@ -6,7 +6,7 @@ const utils = require('../../utils'); module.exports = assignRawDocsToIdStructure; -/*! +/** * Assign `vals` returned by mongo query to the `rawIds` * structure returned from utils.getVals() honoring * query sort order if specified by user. @@ -21,8 +21,10 @@ module.exports = assignRawDocsToIdStructure; * else documents are put back in original order of array if found in results * * @param {Array} rawIds - * @param {Array} vals - * @param {Boolean} sort + * @param {Array} resultDocs + * @param {Array} resultOrder + * @param {Object} options + * @param {Boolean} recursed * @api private */ diff --git a/lib/helpers/populate/assignVals.js b/lib/helpers/populate/assignVals.js index 6e3e4a5029a..651a48e4887 100644 --- a/lib/helpers/populate/assignVals.js +++ b/lib/helpers/populate/assignVals.js @@ -212,7 +212,7 @@ function numDocs(v) { return v == null ? 0 : 1; } -/*! +/** * 1) Apply backwards compatible find/findOne behavior to sub documents * * find logic: @@ -228,6 +228,12 @@ function numDocs(v) { * background: * _ids are left in the query even when user excludes them so * that population mapping can occur. + * @param {Any} val + * @param {Object} assignmentOpts + * @param {Object} populateOptions + * @param {Function} [populateOptions.transform] + * @param {Boolean} allIds + * @api private */ function valueFilter(val, assignmentOpts, populateOptions, allIds) { @@ -288,8 +294,11 @@ function valueFilter(val, assignmentOpts, populateOptions, allIds) { return val == null ? transform(val, allIds) : transform(null, allIds); } -/*! +/** * Remove _id from `subdoc` if user specified "lean" query option + * @param {Document} subdoc + * @param {Object} assignmentOpts + * @api private */ function maybeRemoveId(subdoc, assignmentOpts) { @@ -302,9 +311,11 @@ function maybeRemoveId(subdoc, assignmentOpts) { } } -/*! +/** * Determine if `obj` is something we can set a populated path to. Can be a * document, a lean document, or an array/map that contains docs. + * @param {Any} obj + * @api private */ function isPopulatedObject(obj) { diff --git a/lib/helpers/populate/createPopulateQueryFilter.js b/lib/helpers/populate/createPopulateQueryFilter.js index b93d1ada3d8..810f31a2830 100644 --- a/lib/helpers/populate/createPopulateQueryFilter.js +++ b/lib/helpers/populate/createPopulateQueryFilter.js @@ -44,9 +44,13 @@ module.exports = function createPopulateQueryFilter(ids, _match, _foreignField, return match; }; -/*! +/** * Optionally filter out invalid ids that don't conform to foreign field's schema * to avoid cast errors (gh-7706) + * @param {Array} ids + * @param {SchemaType} foreignSchemaType + * @param {Boolean} [skipInvalidIds] + * @api private */ function _filterInvalidIds(ids, foreignSchemaType, skipInvalidIds) { @@ -64,9 +68,11 @@ function _filterInvalidIds(ids, foreignSchemaType, skipInvalidIds) { }); } -/*! +/** * Format `mod.match` given that it may be an array that we need to $or if * the client has multiple docs with match functions + * @param {Array|Any} match + * @api private */ function _formatMatch(match) { diff --git a/lib/helpers/populate/getModelsMapForPopulate.js b/lib/helpers/populate/getModelsMapForPopulate.js index c058fb0d85e..d767c369578 100644 --- a/lib/helpers/populate/getModelsMapForPopulate.js +++ b/lib/helpers/populate/getModelsMapForPopulate.js @@ -624,11 +624,13 @@ function _getLocalFieldValues(doc, localField, model, options, virtual, schema) } } -/*! +/** * Retrieve the _id of `val` if a Document or Array of Documents. * * @param {Array|Document|Any} val + * @param {Schema} schema * @return {Array|Document|Any} + * @api private */ function convertTo_id(val, schema) { diff --git a/lib/helpers/populate/getSchemaTypes.js b/lib/helpers/populate/getSchemaTypes.js index 76c428653be..177e7889344 100644 --- a/lib/helpers/populate/getSchemaTypes.js +++ b/lib/helpers/populate/getSchemaTypes.js @@ -12,15 +12,17 @@ const mpath = require('mpath'); const populateModelSymbol = require('../symbols').populateModelSymbol; -/*! +/** * Given a model and its schema, find all possible schema types for `path`, * including searching through discriminators. If `doc` is specified, will * use the doc's values for discriminator keys when searching, otherwise * will search all discriminators. * + * @param {Model} model * @param {Schema} schema * @param {Object} doc POJO * @param {string} path + * @api private */ module.exports = function getSchemaTypes(model, schema, doc, path) { diff --git a/lib/helpers/populate/markArraySubdocsPopulated.js b/lib/helpers/populate/markArraySubdocsPopulated.js index 7f15d4367bd..28b19a1989a 100644 --- a/lib/helpers/populate/markArraySubdocsPopulated.js +++ b/lib/helpers/populate/markArraySubdocsPopulated.js @@ -2,7 +2,7 @@ const utils = require('../../utils'); -/*! +/** * If populating a path within a document array, make sure each * subdoc within the array knows its subpaths are populated. * @@ -10,6 +10,10 @@ const utils = require('../../utils'); * * const doc = await Article.findOne().populate('comments.author'); * doc.comments[0].populated('author'); // Should be set + * + * @param {Document} doc + * @param {Object} [populated] + * @api private */ module.exports = function markArraySubdocsPopulated(doc, populated) { diff --git a/lib/helpers/projection/hasIncludedChildren.js b/lib/helpers/projection/hasIncludedChildren.js index a73f4487a85..d757b2c677e 100644 --- a/lib/helpers/projection/hasIncludedChildren.js +++ b/lib/helpers/projection/hasIncludedChildren.js @@ -1,6 +1,6 @@ 'use strict'; -/*! +/** * Creates an object that precomputes whether a given path has child fields in * the projection. * @@ -11,6 +11,9 @@ * res['a.b']; // 1 * res['a.b.c']; // 1 * res['a.c']; // undefined + * + * @param {Object} fields + * @api private */ module.exports = function hasIncludedChildren(fields) { diff --git a/lib/helpers/projection/isPathExcluded.js b/lib/helpers/projection/isPathExcluded.js index fc2592cda52..e0424b52365 100644 --- a/lib/helpers/projection/isPathExcluded.js +++ b/lib/helpers/projection/isPathExcluded.js @@ -2,12 +2,13 @@ const isDefiningProjection = require('./isDefiningProjection'); -/*! +/** * Determines if `path` is excluded by `projection` * * @param {Object} projection - * @param {string} path + * @param {String} path * @return {Boolean} + * @api private */ module.exports = function isPathExcluded(projection, path) { diff --git a/lib/helpers/projection/isSubpath.js b/lib/helpers/projection/isSubpath.js index 4e870e9df0f..bec82f83d9a 100644 --- a/lib/helpers/projection/isSubpath.js +++ b/lib/helpers/projection/isSubpath.js @@ -1,11 +1,12 @@ 'use strict'; -/*! +/** * Determines if `path2` is a subpath of or equal to `path1` * * @param {string} path1 * @param {string} path2 * @return {Boolean} + * @api private */ module.exports = function isSubpath(path1, path2) { diff --git a/lib/helpers/query/applyQueryMiddleware.js b/lib/helpers/query/applyQueryMiddleware.js index bbbd2b2a713..692d69cee3a 100644 --- a/lib/helpers/query/applyQueryMiddleware.js +++ b/lib/helpers/query/applyQueryMiddleware.js @@ -16,11 +16,12 @@ applyQueryMiddleware.middlewareFunctions = validOps.concat([ 'validate' ]); -/*! +/** * Apply query middleware * - * @param {Query} query constructor + * @param {Query} Query constructor * @param {Model} model + * @api private */ function applyQueryMiddleware(Query, model) { diff --git a/lib/helpers/query/castUpdate.js b/lib/helpers/query/castUpdate.js index 03566460ab5..998b452b6d2 100644 --- a/lib/helpers/query/castUpdate.js +++ b/lib/helpers/query/castUpdate.js @@ -14,16 +14,17 @@ const schemaMixedSymbol = require('../../schema/symbols').schemaMixedSymbol; const setDottedPath = require('../path/setDottedPath'); const utils = require('../../utils'); -/*! +/** * Casts an update op based on the given schema * * @param {Schema} schema * @param {Object} obj - * @param {Object} options + * @param {Object} [options] * @param {Boolean} [options.overwrite] defaults to false * @param {Boolean|String} [options.strict] defaults to true * @param {Query} context passed to setters * @return {Boolean} true iff the update is non-empty + * @api private */ module.exports = function castUpdate(schema, obj, options, context, filter) { if (obj == null) { @@ -150,16 +151,17 @@ function castPipelineOperator(op, val) { throw new MongooseError('Invalid update pipeline operator: "' + op + '"'); } -/*! +/** * Walk each path of obj and cast its values * according to its schema. * * @param {Schema} schema * @param {Object} obj part of a query * @param {String} op the atomic operator ($pull, $set, etc) - * @param {Object} options + * @param {Object} [options] * @param {Boolean|String} [options.strict] * @param {Query} context + * @param {Object} filter * @param {String} pref path prefix (internal only) * @return {Bool} true if this path has keys to update * @api private @@ -407,9 +409,10 @@ function _appendError(error, query, key, aggregatedError) { return aggregatedError; } -/*! +/** * These operators should be cast to numbers instead * of their path schema type. + * @api private */ const numberOps = { @@ -417,17 +420,19 @@ const numberOps = { $inc: 1 }; -/*! +/** * These ops require no casting because the RHS doesn't do anything. + * @api private */ const noCastOps = { $unset: 1 }; -/*! +/** * These operators require casting docs * to real Documents for Update operations. + * @api private */ const castOps = { @@ -446,7 +451,7 @@ const overwriteOps = { $setOnInsert: 1 }; -/*! +/** * Casts `val` according to `schema` and atomic `op`. * * @param {SchemaType} schema @@ -454,6 +459,7 @@ const overwriteOps = { * @param {String} op the atomic operator ($pull, $set, etc) * @param {String} $conditional * @param {Query} context + * @param {String} path * @api private */ diff --git a/lib/helpers/query/completeMany.js b/lib/helpers/query/completeMany.js index b52da432a3e..4ba8c2b083e 100644 --- a/lib/helpers/query/completeMany.js +++ b/lib/helpers/query/completeMany.js @@ -5,7 +5,7 @@ const immediate = require('../immediate'); module.exports = completeMany; -/*! +/** * Given a model and an array of docs, hydrates all the docs to be instances * of the model. Used to initialize docs returned from the db from `find()` * @@ -13,10 +13,11 @@ module.exports = completeMany; * @param {Array} docs * @param {Object} fields the projection used, including `select` from schemas * @param {Object} userProvidedFields the user-specified projection - * @param {Object} opts + * @param {Object} [opts] * @param {Array} [opts.populated] * @param {ClientSession} [opts.session] * @param {Function} callback + * @api private */ function completeMany(model, docs, fields, userProvidedFields, opts, callback) { diff --git a/lib/helpers/query/getEmbeddedDiscriminatorPath.js b/lib/helpers/query/getEmbeddedDiscriminatorPath.js index 2f3f39d97e0..f376916b590 100644 --- a/lib/helpers/query/getEmbeddedDiscriminatorPath.js +++ b/lib/helpers/query/getEmbeddedDiscriminatorPath.js @@ -5,9 +5,15 @@ const get = require('../get'); const getDiscriminatorByValue = require('../discriminator/getDiscriminatorByValue'); const updatedPathsByArrayFilter = require('../update/updatedPathsByArrayFilter'); -/*! +/** * Like `schema.path()`, except with a document, because impossible to * determine path type without knowing the embedded discriminator key. + * @param {Schema} schema + * @param {Object} [update] + * @param {Object} [filter] + * @param {String} path + * @param {Object} [options] + * @api private */ module.exports = function getEmbeddedDiscriminatorPath(schema, update, filter, path, options) { diff --git a/lib/helpers/query/wrapThunk.js b/lib/helpers/query/wrapThunk.js index 2c4d3d8a256..1303a4708d6 100644 --- a/lib/helpers/query/wrapThunk.js +++ b/lib/helpers/query/wrapThunk.js @@ -2,13 +2,15 @@ const MongooseError = require('../../error/mongooseError'); -/*! +/** * A query thunk is the function responsible for sending the query to MongoDB, * like `Query#_findOne()` or `Query#_execUpdate()`. The `Query#exec()` function * calls a thunk. The term "thunk" here is the traditional Node.js definition: * a function that takes exactly 1 parameter, a callback. * * This function defines common behavior for all query thunks. + * @param {Function} fn + * @api private */ module.exports = function wrapThunk(fn) { diff --git a/lib/helpers/schema/getIndexes.js b/lib/helpers/schema/getIndexes.js index 7433b8dcfc4..28e0a3e6f5b 100644 --- a/lib/helpers/schema/getIndexes.js +++ b/lib/helpers/schema/getIndexes.js @@ -4,9 +4,11 @@ const get = require('../get'); const helperIsObject = require('../isObject'); const decorateDiscriminatorIndexOptions = require('../indexes/decorateDiscriminatorIndexOptions'); -/*! +/** * Gather all indexes defined in the schema, including single nested, * document arrays, and embedded discriminators. + * @param {Schema} schema + * @api private */ module.exports = function getIndexes(schema) { @@ -120,11 +122,14 @@ module.exports = function getIndexes(schema) { } } - /*! + /** * Checks for indexes added to subdocs using Schema.index(). * These indexes need their paths prefixed properly. * * schema._indexes = [ [indexObj, options], [indexObj, options] ..] + * @param {Schema} schema + * @param {String} prefix + * @api private */ function fixSubIndexPaths(schema, prefix) { diff --git a/lib/helpers/schema/getPath.js b/lib/helpers/schema/getPath.js index 9571e866fb7..b4022826e38 100644 --- a/lib/helpers/schema/getPath.js +++ b/lib/helpers/schema/getPath.js @@ -1,12 +1,13 @@ 'use strict'; -/*! +const numberRE = /^\d+$/; + +/** * Behaves like `Schema#path()`, except for it also digs into arrays without * needing to put `.0.`, so `getPath(schema, 'docArr.elProp')` works. + * @api private */ -const numberRE = /^\d+$/; - module.exports = function getPath(schema, path) { let schematype = schema.path(path); if (schematype != null) { diff --git a/lib/helpers/schema/idGetter.js b/lib/helpers/schema/idGetter.js index 5a0741773f8..31ea2ec8659 100644 --- a/lib/helpers/schema/idGetter.js +++ b/lib/helpers/schema/idGetter.js @@ -18,8 +18,9 @@ module.exports = function addIdGetter(schema) { return schema; }; -/*! +/** * Returns this documents _id cast to a string. + * @api private */ function idGetter() { diff --git a/lib/index.js b/lib/index.js index 49ccb49bde5..e728131fcfe 100644 --- a/lib/index.js +++ b/lib/index.js @@ -1262,10 +1262,10 @@ Mongoose.prototype.skipMiddlewareFunction = Kareem.skipWrappedFunction; Mongoose.prototype.overwriteMiddlewareResult = Kareem.overwriteResult; -/*! +/** * The exports object is an instance of Mongoose. * - * @api public + * @api private */ const mongoose = module.exports = exports = new Mongoose({ diff --git a/lib/model.js b/lib/model.js index 1be0e4b646b..df5a824246e 100644 --- a/lib/model.js +++ b/lib/model.js @@ -119,11 +119,12 @@ function Model(doc, fields, skipId) { Document.call(this, doc, fields, skipId); } -/*! +/** * Inherits from Document. * * All Model.prototype features are available on * top level (non-sub) documents. + * @api private */ Model.prototype.__proto__ = Document.prototype; @@ -222,7 +223,7 @@ Model.prototype.baseModelName; Model.events; -/*! +/** * Compiled middleware for this model. Set in `applyHooks()`. * * @api private @@ -538,12 +539,13 @@ Model.prototype.save = function(options, fn) { Model.prototype.$save = Model.prototype.save; -/*! +/** * Determines whether versioning should be skipped for the given path * * @param {Document} self * @param {String} path * @return {Boolean} true if versioning should be skipped for the given path + * @api private */ function shouldSkipVersioning(self, path) { const skipVersioning = self.$__schema.options.skipVersioning; @@ -555,16 +557,17 @@ function shouldSkipVersioning(self, path) { return skipVersioning[path]; } -/*! +/** * Apply the operation to the delta (update) clause as * well as track versioning for our where clause. * * @param {Document} self - * @param {Object} where + * @param {Object} where Unused * @param {Object} delta * @param {Object} data * @param {Mixed} val - * @param {String} [operation] + * @param {String} [op] + * @api private */ function operand(self, where, delta, data, val, op) { @@ -623,7 +626,7 @@ function operand(self, where, delta, data, val, op) { } } -/*! +/** * Compiles an update and where clause for a `val` with _atomics. * * @param {Document} self @@ -631,6 +634,7 @@ function operand(self, where, delta, data, val, op) { * @param {Object} delta * @param {Object} data * @param {Array} value + * @api private */ function handleAtomics(self, where, delta, data, value) { @@ -797,14 +801,16 @@ Model.prototype.$__delta = function() { return [where, delta]; }; -/*! +/** * Determine if array was populated with some form of filter and is now * being updated in a manner which could overwrite data unintentionally. * * @see https://github.com/Automattic/mongoose/issues/1334 * @param {Document} doc * @param {String} path + * @param {Any} array * @return {String|undefined} + * @api private */ function checkDivergentArray(doc, path, array) { @@ -990,8 +996,14 @@ Model.prototype.remove = function remove(options, fn) { }, this.constructor.events); }; -/*! +/** * Alias for remove + * + * @method $remove + * @memberOf Model + * @instance + * @api public + * @see Model.remove #model_Model-remove */ Model.prototype.$remove = Model.prototype.remove; @@ -1240,8 +1252,9 @@ Model.discriminator = function(name, schema, options) { return d; }; -/*! +/** * Make sure `this` is a model + * @api private */ function _checkContext(ctx, fnName) { @@ -1837,17 +1850,18 @@ function _ensureIndexes(model, options, callback) { Model.schema; -/*! +/** * Connection instance the model uses. * * @property db + * @static * @api public * @memberOf Model */ Model.db; -/*! +/** * Collection the model uses. * * @property collection @@ -2583,8 +2597,9 @@ Model.findOneAndUpdate = function(conditions, update, options, callback) { return mq.findOneAndUpdate(conditions, update, options, callback); }; -/*! +/** * Decorate the update with a version key, if necessary + * @api private */ function _decorateUpdateWithVersionKey(update, options, versionKey) { @@ -3287,8 +3302,16 @@ Model.insertMany = function(arr, options, callback) { }, this.events); }; -/*! +/** * ignore + * + * @param {Array} arr + * @param {Object} options + * @param {Function} callback + * @api private + * @memberOf Model + * @method $__insertMany + * @static */ Model.$__insertMany = function(arr, options, callback) { @@ -4100,9 +4123,10 @@ Model.replaceOne = function replaceOne(conditions, doc, options, callback) { return _update(this, 'replaceOne', conditions, doc, options, callback); }; -/*! +/** * Common code for `updateOne()`, `updateMany()`, `replaceOne()`, and `update()` * because they need to do the same thing + * @api private */ function _update(model, op, conditions, doc, options, callback) { @@ -4513,13 +4537,14 @@ Model.populate = function(docs, paths, callback) { }, this.events); }; -/*! +/** * Populate helper * * @param {Model} model the model to use * @param {Document|Array} docs Either a single document or array of documents to populate. * @param {Object} paths - * @param {Function} [cb(err,doc)] Optional callback, executed upon completion. Receives `err` and the `doc(s)`. + * @param {never} cache Unused + * @param {Function} [callback] Optional callback, executed upon completion. Receives `err` and the `doc(s)`. * @return {Function} * @api private */ @@ -4890,7 +4915,7 @@ function _assign(model, vals, mod, assignmentOpts) { }); } -/*! +/** * Compiler utility. * * @param {String|Function} name model name or class extending Model @@ -4898,6 +4923,7 @@ function _assign(model, vals, mod, assignmentOpts) { * @param {String} collectionName * @param {Connection} connection * @param {Mongoose} base mongoose instance + * @api private */ Model.compile = function compile(name, schema, collectionName, connection, base) { @@ -5006,11 +5032,12 @@ Model.compile = function compile(name, schema, collectionName, connection, base) return model; }; -/*! +/** * Register custom query methods for this model * * @param {Model} model * @param {Schema} schema + * @api private */ function applyQueryMethods(model, methods) { @@ -5019,13 +5046,17 @@ function applyQueryMethods(model, methods) { } } -/*! +/** * Subclass this model with `conn`, `schema`, and `collection` settings. * * @param {Connection} conn * @param {Schema} [schema] * @param {String} [collection] * @return {Model} + * @api private + * @memberOf Model + * @static + * @method __subclass */ Model.__subclass = function subclass(conn, schema, collection) { @@ -5102,8 +5133,14 @@ Model.$handleCallbackError = function(callback) { }; }; -/*! +/** * ignore + * + * @param {Function} callback + * @api private + * @method $wrapCallback + * @memberOf Model + * @static */ Model.$wrapCallback = function(callback) { @@ -5140,10 +5177,7 @@ Model.inspect = function() { }; if (util.inspect.custom) { - /*! - * Avoid Node deprecation warning DEP0079 - */ - + // Avoid Node deprecation warning DEP0079 Model[util.inspect.custom] = Model.inspect; } diff --git a/lib/query.js b/lib/query.js index cbc1034267f..953977c262b 100644 --- a/lib/query.js +++ b/lib/query.js @@ -1211,8 +1211,13 @@ Query.prototype.read = function read(pref, tags) { return this; }; -/*! - * ignore +/** + * Overwrite default `.toString` to make logging more useful + * + * @memberOf Query + * @instance + * @method toString + * @api private */ Query.prototype.toString = function toString() { @@ -2127,8 +2132,12 @@ Query.prototype.error = function error(err) { return this; }; -/*! +/** * ignore + * @method _unsetCastError + * @instance + * @memberOf Query + * @api private */ Query.prototype._unsetCastError = function _unsetCastError() { @@ -2164,8 +2173,12 @@ Query.prototype.mongooseOptions = function(v) { return this._mongooseOptions; }; -/*! +/** * ignore + * @method _castConditions + * @memberOf Query + * @api private + * @instance */ Query.prototype._castConditions = function() { @@ -3032,8 +3045,13 @@ Query.prototype.remove = function(filter, callback) { return this; }; -/*! +/** * ignore + * @param {Function} callback + * @method _remove + * @memberOf Query + * @instance + * @api private */ Query.prototype._remove = wrapThunk(function(callback) { @@ -3118,8 +3136,13 @@ Query.prototype.deleteOne = function(filter, options, callback) { return this; }; -/*! +/** * Internal thunk for `deleteOne()` + * @param {Function} callback + * @method _deleteOne + * @instance + * @memberOf Query + * @api private */ Query.prototype._deleteOne = wrapThunk(function(callback) { @@ -3204,8 +3227,13 @@ Query.prototype.deleteMany = function(filter, options, callback) { return this; }; -/*! +/** * Internal thunk around `deleteMany()` + * @param {Function} callback + * @method _deleteMany + * @instance + * @memberOf Query + * @api private */ Query.prototype._deleteMany = wrapThunk(function(callback) { @@ -3221,7 +3249,7 @@ Query.prototype._deleteMany = wrapThunk(function(callback) { return Query.base.deleteMany.call(this, callback); }); -/*! +/** * hydrates a document * * @param {Model} model @@ -3231,6 +3259,7 @@ Query.prototype._deleteMany = wrapThunk(function(callback) { * @param {Query} self * @param {Array} [pop] array of paths used in population * @param {Function} callback + * @api private */ function completeOne(model, doc, res, options, fields, userProvidedFields, pop, callback) { @@ -3265,8 +3294,10 @@ function completeOne(model, doc, res, options, fields, userProvidedFields, pop, } } -/*! +/** * If the model is a discriminator type and not root, then add the key & value to the criteria. + * @param {Query} query + * @api private */ function prepareDiscriminatorCriteria(query) { @@ -3415,10 +3446,12 @@ Query.prototype.findOneAndUpdate = function(criteria, doc, options, callback) { return this; }; -/*! +/** * Thunk around findOneAndUpdate() * * @param {Function} [callback] + * @method _findOneAndUpdate + * @memberOf Query * @api private */ @@ -3599,11 +3632,13 @@ Query.prototype.findOneAndDelete = function(conditions, options, callback) { return this; }; -/*! +/** * Thunk around findOneAndDelete() * * @param {Function} [callback] * @return {Query} this + * @method _findOneAndDelete + * @memberOf Query * @api private */ Query.prototype._findOneAndDelete = wrapThunk(function(callback) { @@ -3750,11 +3785,14 @@ Query.prototype.findOneAndReplace = function(filter, replacement, options, callb return this; }; -/*! +/** * Thunk around findOneAndReplace() * * @param {Function} [callback] * @return {Query} this + * @method _findOneAndReplace + * @instance + * @memberOf Query * @api private */ Query.prototype._findOneAndReplace = wrapThunk(function(callback) { @@ -3827,9 +3865,10 @@ Query.prototype._findOneAndReplace = wrapThunk(function(callback) { }); }); -/*! +/** * Support the `new` option as an alternative to `returnOriginal` for backwards * compat. + * @api private */ function convertNewToReturnDocument(options) { @@ -3847,11 +3886,14 @@ function convertNewToReturnDocument(options) { } } -/*! +/** * Thunk around findOneAndRemove() * * @param {Function} [callback] * @return {Query} this + * @method _findOneAndRemove + * @memberOf Query + * @instance * @api private */ Query.prototype._findOneAndRemove = wrapThunk(function(callback) { @@ -3863,8 +3905,12 @@ Query.prototype._findOneAndRemove = wrapThunk(function(callback) { this._findAndModify('remove', callback); }); -/*! +/** * Get options from query opts, falling back to the base mongoose object. + * @param {Query} query + * @param {Object} option + * @param {Any} def + * @api private */ function _getOption(query, option, def) { @@ -3879,11 +3925,14 @@ function _getOption(query, option, def) { return def; } -/*! +/** * Override mquery.prototype._findAndModify to provide casting etc. * * @param {String} type either "remove" or "update" * @param {Function} callback + * @method _findAndModify + * @memberOf Query + * @instance * @api private */ @@ -4094,11 +4143,14 @@ function _completeManyLean(schema, docs, path, opts, callback) { } return callback(null, docs); } -/*! +/** * Override mquery.prototype._mergeUpdate to handle mongoose objects in * updates. * * @param {Object} doc + * @method _mergeUpdate + * @memberOf Query + * @instance * @api private */ @@ -4130,9 +4182,12 @@ Query.prototype._mergeUpdate = function(doc) { } }; -/*! +/** * The mongodb driver 1.3.23 only supports the nested array sort * syntax. We must convert it or sorting findAndModify will not work. + * @param {Object} opts + * @param {Array|Object} opts.sort + * @api private */ function convertSortToArray(opts) { @@ -4229,13 +4284,17 @@ function _updateThunk(op, callback) { return null; } -/*! +/** * Mongoose calls this function internally to validate the query if * `runValidators` is set * * @param {Object} castedDoc the update, after casting * @param {Object} options the options from `_optionsForExec()` + * @param {Boolean} isOverwriting * @param {Function} callback + * @method validate + * @memberOf Query + * @instance * @api private */ @@ -4255,44 +4314,56 @@ Query.prototype.validate = function validate(castedDoc, options, isOverwriting, }); }; -/*! +/** * Internal thunk for .update() * * @param {Function} callback * @see Model.update #model_Model-update + * @method _execUpdate + * @memberOf Query + * @instance * @api private */ Query.prototype._execUpdate = wrapThunk(function(callback) { return _updateThunk.call(this, 'update', callback); }); -/*! +/** * Internal thunk for .updateMany() * * @param {Function} callback * @see Model.update #model_Model-update + * @method _updateMany + * @memberOf Query + * @instance * @api private */ Query.prototype._updateMany = wrapThunk(function(callback) { return _updateThunk.call(this, 'updateMany', callback); }); -/*! +/** * Internal thunk for .updateOne() * * @param {Function} callback * @see Model.update #model_Model-update + * @method _updateOne + * @memberOf Query + * @instance * @api private */ Query.prototype._updateOne = wrapThunk(function(callback) { return _updateThunk.call(this, 'updateOne', callback); }); -/*! +/** * Internal thunk for .replaceOne() * * @param {Function} callback * @see Model.replaceOne #model_Model-replaceOne + * @method _replaceOne + * @memberOf Query + * @instance * @api private */ Query.prototype._replaceOne = wrapThunk(function(callback) { @@ -4614,8 +4685,15 @@ Query.prototype.replaceOne = function(conditions, doc, options, callback) { return _update(this, 'replaceOne', conditions, doc, options, callback); }; -/*! +/** * Internal helper for update, updateMany, updateOne, replaceOne + * @param {Query} query + * @param {String} op + * @param {Object} filter + * @param {Document} [doc] + * @param {Object} [options] + * @param {Function} callback + * @api private */ function _update(query, op, filter, doc, options, callback) { @@ -4763,8 +4841,11 @@ Query.prototype.orFail = function(err) { return this; }; -/*! +/** * Get the error to throw for `orFail()` + * @param {Error|undefined} err + * @param {Query} query + * @api private */ function _orFailError(err, query) { @@ -4970,11 +5051,15 @@ Query.prototype.post = function(fn) { return this; }; -/*! +/** * Casts obj for an update command. * * @param {Object} obj + * @param {Boolean} overwrite * @return {Object} obj after casting its values + * @method _castUpdate + * @memberOf Query + * @instance * @api private */ @@ -5018,7 +5103,7 @@ Query.prototype._castUpdate = function _castUpdate(obj, overwrite) { }, this, this._conditions); }; -/*! +/** * castQuery * @api private */ @@ -5533,7 +5618,7 @@ Query.prototype.tailable = function(val, opts) { * @api public */ -/*! +/** * Overwriting mquery is needed to support a couple different near() forms found in older * versions of mongoose * near([1,1]) @@ -5541,6 +5626,11 @@ Query.prototype.tailable = function(val, opts) { * near(field, [1,2]) * near(field, 1, 2) * In addition to all of the normal forms supported by mquery + * + * @method near + * @memberOf Query + * @instance + * @api private */ Query.prototype.near = function() { @@ -5692,10 +5782,15 @@ if (Symbol.asyncIterator != null) { * @api public */ -/*! +/** * this is needed to support the mongoose syntax of: * box(field, { ll : [x,y], ur : [x2,y2] }) * box({ ll : [x,y], ur : [x2,y2] }) + * + * @method box + * @memberOf Query + * @instance + * @api private */ Query.prototype.box = function(ll, ur) { diff --git a/lib/queryhelpers.js b/lib/queryhelpers.js index ef75cda362b..4c2e1ce281f 100644 --- a/lib/queryhelpers.js +++ b/lib/queryhelpers.js @@ -12,7 +12,7 @@ const getDiscriminatorByValue = const isDefiningProjection = require('./helpers/projection/isDefiningProjection'); const clone = require('./helpers/clone'); -/*! +/** * Prepare a set of path options for query population. * * @param {Query} query @@ -38,7 +38,7 @@ exports.preparePopulationOptions = function preparePopulationOptions(query, opti return pop; }; -/*! +/** * Prepare a set of path options for query population. This is the MongooseQuery * version * @@ -82,7 +82,7 @@ exports.preparePopulationOptionsMQ = function preparePopulationOptionsMQ(query, return pop; }; -/*! +/** * If the document is a mapped discriminator type, it returns a model instance for that type, otherwise, * it returns an instance of the given model. * @@ -321,7 +321,7 @@ exports.applyPaths = function applyPaths(fields, schema) { } }; -/*! +/** * Set each path query option to lean * * @param {Object} option diff --git a/lib/schema.js b/lib/schema.js index f202c5aca45..58bd244fb3a 100644 --- a/lib/schema.js +++ b/lib/schema.js @@ -165,8 +165,9 @@ function Schema(obj, options) { this.setupTimestamp(this.options.timestamps); } -/*! +/** * Create virtual properties with alias field + * @api private */ function aliasFields(schema, paths) { paths = paths || Object.keys(schema.paths); @@ -1482,8 +1483,11 @@ Schema.prototype.setupTimestamp = function(timestamps) { return setupTimestamps(this, timestamps); }; -/*! +/** * ignore. Deprecated re: #6405 + * @param {Any} self + * @param {String} path + * @api private */ function getPositionalPathType(self, path) { @@ -2427,9 +2431,13 @@ function isArrayFilter(piece) { return piece.startsWith('$[') && piece.endsWith(']'); } -/*! +/** * Called by `compile()` _right before_ compiling. Good for making any changes to * the schema that should respect options set by plugins, like `id` + * @method _preCompile + * @memberOf Schema + * @instance + * @api private */ Schema.prototype._preCompile = function _preCompile() { diff --git a/lib/schema/SubdocumentPath.js b/lib/schema/SubdocumentPath.js index 13ad69ddcbf..04b62cf4d19 100644 --- a/lib/schema/SubdocumentPath.js +++ b/lib/schema/SubdocumentPath.js @@ -107,7 +107,7 @@ function _createConstructor(schema, baseClass) { return _embedded; } -/*! +/** * Special case for when users use a common location schema to represent * locations for use with $geoWithin. * https://docs.mongodb.org/manual/reference/operator/query/geoWithin/ diff --git a/lib/schema/array.js b/lib/schema/array.js index 1dbe8556708..84c664ff63b 100644 --- a/lib/schema/array.js +++ b/lib/schema/array.js @@ -448,7 +448,7 @@ SchemaArray.prototype._castForPopulate = function _castForPopulate(value, doc) { SchemaArray.prototype.$toObject = SchemaArray.prototype.toObject; /*! - * Ignore + * ignore */ SchemaArray.prototype.discriminator = function(name, schema) { diff --git a/lib/schema/date.js b/lib/schema/date.js index 4edc764210a..feafe4709ef 100644 --- a/lib/schema/date.js +++ b/lib/schema/date.js @@ -355,9 +355,10 @@ SchemaDate.prototype.cast = function(value) { } }; -/*! +/** * Date Query casting. * + * @param {Any} val * @api private */ diff --git a/lib/schema/documentarray.js b/lib/schema/documentarray.js index 0bb64d779cf..b9066921cb9 100644 --- a/lib/schema/documentarray.js +++ b/lib/schema/documentarray.js @@ -123,7 +123,7 @@ DocumentArrayPath.prototype.constructor = DocumentArrayPath; DocumentArrayPath.prototype.OptionsConstructor = SchemaDocumentArrayOptions; /*! - * Ignore + * ignore */ function _createConstructor(schema, options, baseClass) { @@ -545,13 +545,14 @@ DocumentArrayPath.prototype.applyGetters = function(value, scope) { return SchemaType.prototype.applyGetters.call(this, value, scope); }; -/*! +/** * Scopes paths selected in a query to this array. * Necessary for proper default application of subdocument values. * * @param {DocumentArrayPath} array the array to scope `fields` paths * @param {Object|undefined} fields the root fields selected in the query * @param {Boolean|undefined} init if we are being created part of a query result + * @api private */ function scopePaths(array, fields, init) { diff --git a/lib/schema/operators/helpers.js b/lib/schema/operators/helpers.js index a17951cd72e..4690ca3c5ae 100644 --- a/lib/schema/operators/helpers.js +++ b/lib/schema/operators/helpers.js @@ -7,14 +7,14 @@ const SchemaNumber = require('../number'); /*! - * @ignore + * ignore */ exports.castToNumber = castToNumber; exports.castArraysOfNumbers = castArraysOfNumbers; /*! - * @ignore + * ignore */ function castToNumber(val) { diff --git a/lib/schema/operators/text.js b/lib/schema/operators/text.js index 4b959168dd9..f4734345b1b 100644 --- a/lib/schema/operators/text.js +++ b/lib/schema/operators/text.js @@ -4,7 +4,7 @@ const CastError = require('../../error/cast'); const castBoolean = require('../../cast/boolean'); const castString = require('../../cast/string'); -/*! +/** * Casts val to an object suitable for `$text`. Throws an error if the object * can't be casted. * diff --git a/lib/schematype.js b/lib/schematype.js index a1418c68098..0cc6c3eea59 100644 --- a/lib/schematype.js +++ b/lib/schematype.js @@ -124,8 +124,11 @@ function SchemaType(path, options, instance) { }); } -/*! +/** * The class that Mongoose uses internally to instantiate this SchemaType's `options` property. + * @memberOf SchemaType + * @instance + * @api private */ SchemaType.prototype.OptionsConstructor = SchemaTypeOptions; @@ -1144,9 +1147,15 @@ SchemaType.prototype.getDefault = function(scope, init, options) { return ret; }; -/*! +/** * Applies setters without casting * + * @param {Any} value + * @param {Any} scope + * @param {Boolean} init + * @param {Any} priorVal + * @param {Object} [options] + * @instance * @api private */ @@ -1547,9 +1556,10 @@ function handleArray(val) { }); } -/*! +/** * Just like handleArray, except also allows `[]` because surprisingly * `$in: [1, []]` works fine + * @api private */ function handle$in(val) { @@ -1579,8 +1589,11 @@ SchemaType.prototype.$conditionalHandlers = { $type: $type }; -/*! +/** * Wraps `castForQuery` to handle context + * @param {Object} params + * @instance + * @api private */ SchemaType.prototype.castForQueryWrapper = function(params) { diff --git a/lib/statemachine.js b/lib/statemachine.js index a524c999939..70b1beca695 100644 --- a/lib/statemachine.js +++ b/lib/statemachine.js @@ -7,7 +7,7 @@ const utils = require('./utils'); // eslint-disable-line no-unused-vars -/*! +/** * StateMachine represents a minimal `interface` for the * constructors it builds via StateMachine.ctor(...). * @@ -17,7 +17,7 @@ const utils = require('./utils'); // eslint-disable-line no-unused-vars const StateMachine = module.exports = exports = function StateMachine() { }; -/*! +/** * StateMachine.ctor('state1', 'state2', ...) * A factory method for subclassing StateMachine. * The arguments are a list of states. For each state, @@ -28,7 +28,7 @@ const StateMachine = module.exports = exports = function StateMachine() { * @param {String} state * @param {String} [state] * @return {Function} subclass constructor - * @private + * @api private */ StateMachine.ctor = function() { @@ -54,7 +54,7 @@ StateMachine.ctor = function() { return ctor; }; -/*! +/** * This function is wrapped by the state change functions: * * - `require(path)` @@ -105,8 +105,9 @@ StateMachine.prototype.clearPath = function clearPath(path) { delete this.states[state][path]; }; -/*! +/** * Gets the paths for the given state, or empty object `{}` if none. + * @api private */ StateMachine.prototype.getStatePaths = function getStatePaths(state) { @@ -116,12 +117,12 @@ StateMachine.prototype.getStatePaths = function getStatePaths(state) { return {}; }; -/*! +/** * Checks to see if at least one path is in the states passed in via `arguments` * e.g., this.some('required', 'inited') * * @param {String} state that we want to check for. - * @private + * @api private */ StateMachine.prototype.some = function some() { @@ -135,7 +136,7 @@ StateMachine.prototype.some = function some() { }); }; -/*! +/** * This function builds the functions that get assigned to `forEach` and `map`, * since both of those methods share a lot of the same logic. * @@ -166,7 +167,7 @@ StateMachine.prototype._iter = function _iter(iterMethod) { }; }; -/*! +/** * Iterates over the paths that belong to one of the parameter states. * * The function profile can look like: @@ -177,7 +178,7 @@ StateMachine.prototype._iter = function _iter(iterMethod) { * @param {String} [state] * @param {String} [state] * @param {Function} callback - * @private + * @api private */ StateMachine.prototype.forEach = function forEach() { @@ -185,7 +186,7 @@ StateMachine.prototype.forEach = function forEach() { return this.forEach.apply(this, arguments); }; -/*! +/** * Maps over the paths that belong to one of the parameter states. * * The function profile can look like: @@ -197,7 +198,7 @@ StateMachine.prototype.forEach = function forEach() { * @param {String} [state] * @param {Function} callback * @return {Array} - * @private + * @api private */ StateMachine.prototype.map = function map() { diff --git a/lib/types/ArraySubdocument.js b/lib/types/ArraySubdocument.js index b5118c9c9b4..c5ac4ed9768 100644 --- a/lib/types/ArraySubdocument.js +++ b/lib/types/ArraySubdocument.js @@ -10,12 +10,14 @@ const utils = require('../utils'); const documentArrayParent = require('../helpers/symbols').documentArrayParent; -/*! +/** * A constructor. * * @param {Object} obj js object returned from the db * @param {MongooseDocumentArray} parentArr the parent array of this document * @param {Boolean} skipId + * @param {Object} Fields + * @param {Number} index * @inherits Document * @api private */ @@ -125,9 +127,13 @@ ArraySubdocument.prototype.$__fullPath = function(path, skipIndex) { this.$__.fullPath + '.' + this.__index; }; -/*! +/** * Given a path relative to this document, return the path relative * to the top-level document. + * @method $__pathRelativeToParent + * @memberOf ArraySubdocument + * @instance + * @api private */ ArraySubdocument.prototype.$__pathRelativeToParent = function(path, skipIndex) { @@ -143,8 +149,12 @@ ArraySubdocument.prototype.$__pathRelativeToParent = function(path, skipIndex) { return this.__parentArray.$path() + '.' + this.__index + '.' + path; }; -/*! +/** * Returns this sub-documents parent document. + * @method $parent + * @memberOf ArraySubdocument + * @instance + * @api public */ ArraySubdocument.prototype.$parent = function() { diff --git a/lib/types/DocumentArray/methods/index.js b/lib/types/DocumentArray/methods/index.js index 66c55678a94..23fcfbab167 100644 --- a/lib/types/DocumentArray/methods/index.js +++ b/lib/types/DocumentArray/methods/index.js @@ -212,8 +212,9 @@ const methods = { return ret; }, - /*! + /** * Wraps [`Array#shift`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/unshift) with proper change tracking. + * @api private */ shift() { @@ -224,8 +225,9 @@ const methods = { return ret; }, - /*! + /** * Wraps [`Array#splice`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/splice) with proper change tracking and casting. + * @api private */ splice() { @@ -355,10 +357,12 @@ const methods = { module.exports = methods; -/*! +/** * If this is a document array, each element may contain single * populated paths, so we need to modify the top-level document's * populated cache. See gh-8247, gh-8265. + * @param {Array} arr + * @api private */ function _updateParentPopulated(arr) { diff --git a/lib/types/map.js b/lib/types/map.js index 87e486ed44f..3c68026fa0e 100644 --- a/lib/types/map.js +++ b/lib/types/map.js @@ -295,9 +295,11 @@ Object.defineProperty(MongooseMap.prototype, '$__deferredCalls', { value: true }); -/*! +/** * Since maps are stored as objects under the hood, keys must be strings * and can't contain any invalid characters + * @param {String} key + * @api private */ function checkValidKey(key) { diff --git a/lib/types/objectid.js b/lib/types/objectid.js index ab73119cb55..63c3bd05c81 100644 --- a/lib/types/objectid.js +++ b/lib/types/objectid.js @@ -13,8 +13,9 @@ const ObjectId = require('../driver').get().ObjectId; const objectIdSymbol = require('../helpers/symbols').objectIdSymbol; -/*! +/** * Getter for convenience with populate, see gh-6115 + * @api private */ Object.defineProperty(ObjectId.prototype, '_id', { @@ -29,7 +30,6 @@ Object.defineProperty(ObjectId.prototype, '_id', { * Convenience `valueOf()` to allow comparing ObjectIds using double equals re: gh-7299 */ - if (!ObjectId.prototype.hasOwnProperty('valueOf')) { ObjectId.prototype.valueOf = function objectIdValueOf() { return this.toString(); diff --git a/lib/types/subdocument.js b/lib/types/subdocument.js index 197f086224c..d282f892400 100644 --- a/lib/types/subdocument.js +++ b/lib/types/subdocument.js @@ -86,9 +86,15 @@ Subdocument.prototype.save = function(options, fn) { }); }; -/*! +/** * Given a path relative to this document, return the path relative * to the top-level document. + * @param {String} path + * @method $__fullPath + * @memberOf Subdocument + * @instance + * @returns {String} + * @api private */ Subdocument.prototype.$__fullPath = function(path) { @@ -101,9 +107,15 @@ Subdocument.prototype.$__fullPath = function(path) { this.$__.fullPath; }; -/*! +/** * Given a path relative to this document, return the path relative * to the top-level document. + * @param {String} p + * @returns {String} + * @method $__pathRelativeToParent + * @memberOf Subdocument + * @instance + * @api private */ Subdocument.prototype.$__pathRelativeToParent = function(p) { @@ -317,8 +329,13 @@ Subdocument.prototype.parent = function() { Subdocument.prototype.$parent = Subdocument.prototype.parent; -/*! +/** * no-op for hooks + * @param {Function} cb + * @method $__remove + * @memberOf Subdocument + * @instance + * @api private */ Subdocument.prototype.$__remove = function(cb) { @@ -328,6 +345,14 @@ Subdocument.prototype.$__remove = function(cb) { return cb(null, this); }; +/** + * ignore + * @method $__removeFromParent + * @memberOf Subdocument + * @instance + * @api private + */ + Subdocument.prototype.$__removeFromParent = function() { this.$__parent.set(this.$basePath, null); }; @@ -379,14 +404,11 @@ Subdocument.prototype.inspect = function() { }; if (util.inspect.custom) { - /*! - * Avoid Node deprecation warning DEP0079 - */ - + // Avoid Node deprecation warning DEP0079 Subdocument.prototype[util.inspect.custom] = Subdocument.prototype.inspect; } -/*! +/** * Registers remove event listeners for triggering * on subdocuments. * diff --git a/lib/utils.js b/lib/utils.js index c166056e156..2aa75462037 100644 --- a/lib/utils.js +++ b/lib/utils.js @@ -30,7 +30,7 @@ exports.isMongooseDocumentArray = isMongooseDocumentArray.isMongooseDocumentArra exports.registerMongooseArray = isMongooseArray.registerMongooseArray; exports.registerMongooseDocumentArray = isMongooseDocumentArray.registerMongooseDocumentArray; -/*! +/** * Produces a collection name from model `name`. By default, just returns * the model name * @@ -53,7 +53,7 @@ exports.toCollectionName = function(name, pluralize) { return name; }; -/*! +/** * Determines if `a` and `b` are deep equal. * * Modified from node/lib/assert.js @@ -174,8 +174,9 @@ exports.deepEqual = function deepEqual(a, b) { return true; }; -/*! +/** * Get the last element of an array + * @param {Array} arr */ exports.last = function(arr) { @@ -225,11 +226,11 @@ exports.omit = function omit(obj, keys) { }; -/*! +/** * Shallow copies defaults into options. * * @param {Object} defaults - * @param {Object} options + * @param {Object} [options] * @return {Object} the merged object * @api private */ @@ -251,11 +252,13 @@ exports.options = function(defaults, options) { return options; }; -/*! +/** * Merges `from` into `to` without overwriting existing properties. * * @param {Object} to * @param {Object} from + * @param {Object} [options] + * @param {String} [path] * @api private */ @@ -318,7 +321,7 @@ exports.merge = function merge(to, from, options, path) { } }; -/*! +/** * Applies toObject recursively. * * @param {Document|Array|Object} obj @@ -370,7 +373,7 @@ exports.toObject = function toObject(obj) { exports.isObject = isObject; -/*! +/** * Determines if `arg` is a plain old JavaScript object (POJO). Specifically, * `arg` must be an object but not an instance of any special class, like String, * ObjectId, etc. @@ -393,9 +396,10 @@ exports.isPOJO = function isPOJO(arg) { return !proto || proto.constructor.name === 'Object'; }; -/*! +/** * Determines if `arg` is an object that isn't an instance of a built-in value * class, like Array, Buffer, ObjectId, etc. + * @param {Any} val */ exports.isNonBuiltinObject = function isNonBuiltinObject(val) { @@ -405,9 +409,10 @@ exports.isNonBuiltinObject = function isNonBuiltinObject(val) { val != null; }; -/*! +/** * Determines if `obj` is a built-in object like an array, date, boolean, * etc. + * @param {Any} arg */ exports.isNativeObject = function(arg) { @@ -418,8 +423,9 @@ exports.isNativeObject = function(arg) { arg instanceof String; }; -/*! +/** * Determines if `val` is an object that has no own keys + * @param {Any} val */ exports.isEmptyObject = function(val) { @@ -428,9 +434,11 @@ exports.isEmptyObject = function(val) { Object.keys(val).length === 0; }; -/*! +/** * Search if `obj` or any POJOs nested underneath `obj` has a property named * `key` + * @param {Object} obj + * @param {String} key */ exports.hasKey = function hasKey(obj, key) { @@ -446,7 +454,7 @@ exports.hasKey = function hasKey(obj, key) { return false; }; -/*! +/** * process.nextTick helper. * * Wraps `callback` in a try/catch + nextTick. @@ -474,9 +482,10 @@ exports.tick = function tick(callback) { }; }; -/*! +/** * Returns true if `v` is an object that can be serialized as a primitive in * MongoDB + * @param {Any} v */ exports.isMongooseType = function(v) { @@ -485,7 +494,7 @@ exports.isMongooseType = function(v) { exports.isMongooseObject = isMongooseObject; -/*! +/** * Converts `expires` options of index objects to `expiresAfterSeconds` options for MongoDB. * * @param {Object} object @@ -506,8 +515,16 @@ exports.expires = function expires(object) { delete object.expires; }; -/*! +/** * populate helper + * @param {String} path + * @param {String} select + * @param {Model} model + * @param {Object} match + * @param {Object} options + * @param {Any} subPopulate + * @param {Boolean} justOne + * @param {Boolean} count */ exports.populate = function populate(path, select, model, match, options, subPopulate, justOne, count) { @@ -613,30 +630,33 @@ function _populateObj(obj) { return ret; } -/*! +/** * Return the value of `obj` at the given `path`. * * @param {String} path * @param {Object} obj + * @param {Any} map */ exports.getValue = function(path, obj, map) { return mpath.get(path, obj, '_doc', map); }; -/*! +/** * Sets the value of `obj` at the given `path`. * * @param {String} path * @param {Anything} val * @param {Object} obj + * @param {Any} map + * @param {Any} _copying */ exports.setValue = function(path, val, obj, map, _copying) { mpath.set(path, val, obj, '_doc', map, _copying); }; -/*! +/** * Returns an array of values from object `o`. * * @param {Object} o @@ -657,27 +677,29 @@ exports.object.vals = function vals(o) { return ret; }; -/*! +/** * @see exports.options */ exports.object.shallowCopy = exports.options; -/*! +const hop = Object.prototype.hasOwnProperty; + +/** * Safer helper for hasOwnProperty checks * * @param {Object} obj * @param {String} prop */ -const hop = Object.prototype.hasOwnProperty; exports.object.hasOwnProperty = function(obj, prop) { return hop.call(obj, prop); }; -/*! +/** * Determine if `val` is null or undefined * + * @param {Any} val * @return {Boolean} */ @@ -691,13 +713,14 @@ exports.isNullOrUndefined = function(val) { exports.array = {}; -/*! +/** * Flattens an array. * * [ 1, [ 2, 3, [4] ]] -> [1,2,3,4] * * @param {Array} arr * @param {Function} [filter] If passed, will be invoked with each item in the array. If `filter` returns a falsy value, the item will not be included in the results. + * @param {Array} ret * @return {Array} * @api private */ @@ -770,7 +793,7 @@ exports.isArrayIndex = function(val) { return false; }; -/*! +/** * Removes duplicate values from an array * * [1, 2, 3, 3, 5] => [1, 2, 3, 5] @@ -808,14 +831,15 @@ exports.array.unique = function(arr) { return ret; }; -/*! +exports.buffer = {}; + +/** * Determines if two buffers are equal. * * @param {Buffer} a * @param {Object} b */ -exports.buffer = {}; exports.buffer.areEqual = function(a, b) { if (!Buffer.isBuffer(a)) { return false; @@ -835,8 +859,11 @@ exports.buffer.areEqual = function(a, b) { }; exports.getFunctionName = getFunctionName; -/*! + +/** * Decorate buffers + * @param {Object} destination + * @param {Object} source */ exports.decorate = function(destination, source) { diff --git a/test/common.js b/test/common.js index 1b786d65986..d6aa91160ad 100644 --- a/test/common.js +++ b/test/common.js @@ -114,13 +114,13 @@ module.exports = function(options) { return conn; }; -/*! +/** * testing uri */ module.exports.uri = process.env.MONGOOSE_TEST_URI || 'mongodb://127.0.0.1:27017/mongoose_test'; -/*! +/** * testing uri for 2nd db */ diff --git a/test/util.js b/test/util.js index 287da3bf6a5..9c7f9c3e02d 100644 --- a/test/util.js +++ b/test/util.js @@ -1,9 +1,7 @@ 'use strict'; -/*! +/** * Generates a random string - * - * @api private */ exports.random = function() { From 11edf8dc52fe2e4565c11458b67b963a7f416ca4 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Tue, 30 Aug 2022 17:46:18 +0200 Subject: [PATCH 3/3] style(ArraySubdocument): fix jsdoc field casing --- lib/types/ArraySubdocument.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/types/ArraySubdocument.js b/lib/types/ArraySubdocument.js index c5ac4ed9768..55889caa839 100644 --- a/lib/types/ArraySubdocument.js +++ b/lib/types/ArraySubdocument.js @@ -16,7 +16,7 @@ const documentArrayParent = require('../helpers/symbols').documentArrayParent; * @param {Object} obj js object returned from the db * @param {MongooseDocumentArray} parentArr the parent array of this document * @param {Boolean} skipId - * @param {Object} Fields + * @param {Object} fields * @param {Number} index * @inherits Document * @api private