From 46073dd8267df9ab61da7b09394983bf11fd4569 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 14:22:51 +0200 Subject: [PATCH 01/43] chore: add yarn.lock to ignore --- .gitignore | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index b62e157cc43..95a95fcdf50 100644 --- a/.gitignore +++ b/.gitignore @@ -48,4 +48,7 @@ docs/*.html docs/tutorials/*.html docs/typescript/*.html docs/api/*.html -index.html \ No newline at end of file +index.html + +# yarn package-lock +yarn.lock From f0fa4b505934b9b8accb0f132ab84ab07aad9a26 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 14:45:52 +0200 Subject: [PATCH 02/43] chore: upgrade "dox" to "0.4.4" --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 1ee9873cdc4..43115cb5daa 100644 --- a/package.json +++ b/package.json @@ -42,7 +42,7 @@ "buffer": "^5.6.0", "cheerio": "1.0.0-rc.11", "crypto-browserify": "3.12.0", - "dox": "0.3.1", + "dox": "0.4.4", "eslint": "8.16.0", "eslint-plugin-mocha-no-only": "1.1.1", "highlight.js": "11.5.1", @@ -145,4 +145,4 @@ "target": "ES2017" } } -} \ No newline at end of file +} From a889e3a24de0b99637a9fab4520319ca731a03a8 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 14:46:27 +0200 Subject: [PATCH 03/43] chore: upgrade "dox" to "0.4.5" --- docs/source/api.js | 13 ++++++++++++- package.json | 2 +- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index 9fd275e0406..dad46f20c1b 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -94,7 +94,18 @@ function parse() { break; case 'property': ctx.type = 'property'; - let str = tag.string; + + // transform "tag" properties to how the way before tag 4.5 + // in 4.4 something like "{Connection} connection" or "{Array} connections" was put out, now "tag" contains different properties + // which would look like "tag = { type: 'property', types: ['Connection'], name: 'connection' }" + // or "tag = { type: 'property', types: ['Array'], name: 'connections' }" + let str; + if (tag.name.length > 0) { + str = "{" + tag.types.join(' ') + "} " + tag.name; + } else { + str = tag.types.join(' '); + } + const match = str.match(/^{\w+}/); if (match != null) { ctx.type = match[0].substring(1, match[0].length - 1); diff --git a/package.json b/package.json index 43115cb5daa..dfd8f959d2c 100644 --- a/package.json +++ b/package.json @@ -42,7 +42,7 @@ "buffer": "^5.6.0", "cheerio": "1.0.0-rc.11", "crypto-browserify": "3.12.0", - "dox": "0.4.4", + "dox": "0.4.5", "eslint": "8.16.0", "eslint-plugin-mocha-no-only": "1.1.1", "highlight.js": "11.5.1", From 5de8b9aff41816bfdae5711a788a3ab190c543f3 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 14:56:49 +0200 Subject: [PATCH 04/43] chore(docs/source/api.js): add log of file when "parseComments" errors --- docs/source/api.js | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index dad46f20c1b..e51d6a24f70 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -47,9 +47,15 @@ const out = module.exports.docs; const combinedFiles = []; for (const file of files) { - const comments = dox.parseComments(fs.readFileSync(`./${file}`, 'utf8'), { raw: true }); - comments.file = file; - combinedFiles.push(comments); + try { + const comments = dox.parseComments(fs.readFileSync(`./${file}`, 'utf8'), { raw: true }); + comments.file = file; + combinedFiles.push(comments); + } catch (err) { + // show log of which file has thrown a error for easier debugging + console.error("Error while trying to parseComments for ", file); + throw err; + } } parse(); From aa297ba550f0bcfc4d5cacf5ea7c6299ac4d9503 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 15:02:48 +0200 Subject: [PATCH 05/43] style: fix empty "returns" jsdoc for "syncIndexes" This change is required because since dox 0.5.0 a error will be thrown if "return" present but empty This change also extends the message to say what gets returned --- lib/connection.js | 2 +- lib/index.js | 2 +- lib/model.js | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/connection.js b/lib/connection.js index 310482ce06b..11057ea4b8a 100644 --- a/lib/connection.js +++ b/lib/connection.js @@ -1452,7 +1452,7 @@ Connection.prototype.setClient = function setClient(client) { * * @param {Object} options * @param {Boolean} options.continueOnError `false` by default. If set to `true`, mongoose will not throw an error if one model syncing failed, and will return an object where the keys are the names of the models, and the values are the results/errors for each model. - * @returns + * @return {Promise|undefined} Returns `undefined` if callback is specified, returns a promise if no callback, when the Promise resolves the value is a list of the dropped indexes. */ Connection.prototype.syncIndexes = async function syncIndexes(options = {}) { const result = {}; diff --git a/lib/index.js b/lib/index.js index ce7343ac087..b374f1d4c9b 100644 --- a/lib/index.js +++ b/lib/index.js @@ -1044,7 +1044,7 @@ Mongoose.prototype.isObjectIdOrHexString = function(v) { * * @param {Object} options * @param {Boolean} options.continueOnError `false` by default. If set to `true`, mongoose will not throw an error if one model syncing failed, and will return an object where the keys are the names of the models, and the values are the results/errors for each model. - * @returns + * @return {Promise|undefined} Returns `undefined` if callback is specified, returns a promise if no callback, when the Promise resolves the value is a list of the dropped indexes. */ Mongoose.prototype.syncIndexes = function(options) { const _mongoose = this instanceof Mongoose ? this : mongoose; diff --git a/lib/model.js b/lib/model.js index 6d02eb8d4e8..facd075fc87 100644 --- a/lib/model.js +++ b/lib/model.js @@ -1453,7 +1453,7 @@ Model.createCollection = function createCollection(options, callback) { * @param {Object} [options] options to pass to `ensureIndexes()` * @param {Boolean} [options.background=null] if specified, overrides each index's `background` property * @param {Function} [callback] optional callback - * @return {Promise|undefined} Returns `undefined` if callback is specified, returns a promise if no callback. + * @return {Promise|undefined} Returns `undefined` if callback is specified, returns a promise if no callback, when the Promise resolves the value is a list of the dropped indexes. * @api public */ From b4c26a4af1bc8f8b8f78caddde6a4316b8c5149c Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 15:06:42 +0200 Subject: [PATCH 06/43] style: fix empty "returns" jsdoc for "buildBulkWriteOperations" This change is required because since dox 0.5.0 a error will be thrown if "return" present but empty This change also extends the message to say what gets returned --- lib/model.js | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/model.js b/lib/model.js index facd075fc87..a62e962bc38 100644 --- a/lib/model.js +++ b/lib/model.js @@ -3690,7 +3690,7 @@ function handleSuccessfulWrite(document, resolve, reject) { * @param {[Document]} documents The array of documents to build write operations of * @param {Object} options * @param {Boolean} options.skipValidation defaults to `false`, when set to true, building the write operations will bypass validating the documents. - * @returns + * @return {Array} Returns a array of all Promises the function executes to be awaited. */ Model.buildBulkWriteOperations = function buildBulkWriteOperations(documents, options) { if (!Array.isArray(documents)) { diff --git a/package.json b/package.json index dfd8f959d2c..5b220a209bc 100644 --- a/package.json +++ b/package.json @@ -42,7 +42,7 @@ "buffer": "^5.6.0", "cheerio": "1.0.0-rc.11", "crypto-browserify": "3.12.0", - "dox": "0.4.5", + "dox": "0.5.0", "eslint": "8.16.0", "eslint-plugin-mocha-no-only": "1.1.1", "highlight.js": "11.5.1", From c42bdba17b418783ecf2c83f4dd85c338644965d Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 15:08:43 +0200 Subject: [PATCH 07/43] chore: upgrade "dox" to "0.5.3" --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 5b220a209bc..1791f3f1b1e 100644 --- a/package.json +++ b/package.json @@ -42,7 +42,7 @@ "buffer": "^5.6.0", "cheerio": "1.0.0-rc.11", "crypto-browserify": "3.12.0", - "dox": "0.5.0", + "dox": "0.5.3", "eslint": "8.16.0", "eslint-plugin-mocha-no-only": "1.1.1", "highlight.js": "11.5.1", From dce32d5aead6becb48dfa42604b23a356a9d12b8 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 15:38:20 +0200 Subject: [PATCH 08/43] style: properly define Document Arrays in jsdoc --- lib/model.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/model.js b/lib/model.js index a62e962bc38..dd3d51dd7e0 100644 --- a/lib/model.js +++ b/lib/model.js @@ -3613,7 +3613,7 @@ Model.bulkWrite = function(ops, options, callback) { * * `bulkSave` uses `bulkWrite` under the hood, so it's mostly useful when dealing with many documents (10K+) * - * @param {[Document]} documents + * @param {Array} documents * @param {Object} [options] options passed to the underlying `bulkWrite()` * @param {ClientSession} [options.session=null] The session associated with this bulk write. See [transactions docs](/docs/transactions.html). * @param {String|number} [options.w=1] The [write concern](https://docs.mongodb.com/manual/reference/write-concern/). See [`Query#w()`](/docs/api.html#query_Query-w) for more information. @@ -3687,7 +3687,7 @@ function handleSuccessfulWrite(document, resolve, reject) { /** * - * @param {[Document]} documents The array of documents to build write operations of + * @param {Array} documents The array of documents to build write operations of * @param {Object} options * @param {Boolean} options.skipValidation defaults to `false`, when set to true, building the write operations will bypass validating the documents. * @return {Array} Returns a array of all Promises the function executes to be awaited. From 7155089f33267dd0c468c35a6dff61176c9b04ed Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 15:44:28 +0200 Subject: [PATCH 09/43] style: remove function definition from "VirtualType.get" and "VirtualType.set" This is because dox (jsdoctypeparser@1.2.0) does not seem to recognize "@callback" or "@typedef" with "@name" --- lib/virtualtype.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/virtualtype.js b/lib/virtualtype.js index fcc1187fa9c..bf458154b2c 100644 --- a/lib/virtualtype.js +++ b/lib/virtualtype.js @@ -75,7 +75,7 @@ VirtualType.prototype.clone = function() { * Mongoose calls the getter function with the below 3 parameters. * * - `value`: the value returned by the previous getter. If there is only one getter, `value` will be `undefined`. - * - `virtual`: the virtual object you called `.get()` on + * - `virtual`: the virtual object you called `.get()` on. * - `doc`: the document this virtual is attached to. Equivalent to `this`. * * #### Example: @@ -85,7 +85,7 @@ VirtualType.prototype.clone = function() { * return this.name.first + ' ' + this.name.last; * }); * - * @param {Function(Any, VirtualType, Document)} fn + * @param {function} fn * @return {VirtualType} this * @api public */ @@ -100,8 +100,8 @@ VirtualType.prototype.get = function(fn) { * * Mongoose calls the setter function with the below 3 parameters. * - * - `value`: the value being set - * - `virtual`: the virtual object you're calling `.set()` on + * - `value`: the value being set. + * - `virtual`: the virtual object you're calling `.set()` on. * - `doc`: the document this virtual is attached to. Equivalent to `this`. * * #### Example: @@ -120,7 +120,7 @@ VirtualType.prototype.get = function(fn) { * doc.name.first; // 'Jean-Luc' * doc.name.last; // 'Picard' * - * @param {Function(Any, VirtualType, Document)} fn + * @param {function} fn * @return {VirtualType} this * @api public */ From c22e7cf69af26e56e452e95d6b0b794dcbca57a6 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 16:00:02 +0200 Subject: [PATCH 10/43] style: add jsdoc tags "memberOf" and "instance" to "Mongoose.prototype.Collection" --- lib/index.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/index.js b/lib/index.js index b374f1d4c9b..cda6e724d12 100644 --- a/lib/index.js +++ b/lib/index.js @@ -761,6 +761,8 @@ Mongoose.prototype.Aggregate = Aggregate; /** * The Mongoose Collection constructor * + * @memberOf Mongoose + * @instance * @method Collection * @api public */ From 97b47c320897e339a90c467d1352b51dcce30a8f Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 16:06:05 +0200 Subject: [PATCH 11/43] style: add jsdoc tag "memberOf" to "Model.prototype.increment" --- lib/model.js | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/model.js b/lib/model.js index dd3d51dd7e0..c66828b464f 100644 --- a/lib/model.js +++ b/lib/model.js @@ -899,6 +899,7 @@ Model.prototype.$__version = function(where, delta) { * }) * * @see versionKeys https://mongoosejs.com/docs/guide.html#versionKey + * @memberOf Model * @api public */ From a6c98344977ba124a0f4ab34f7df65193cda45fd Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 16:06:23 +0200 Subject: [PATCH 12/43] style: add jsdoc tag "memberOf" to "QueryCursor.prototype.map" --- lib/cursor/QueryCursor.js | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/cursor/QueryCursor.js b/lib/cursor/QueryCursor.js index 54001d0f441..6327dd4dc9c 100644 --- a/lib/cursor/QueryCursor.js +++ b/lib/cursor/QueryCursor.js @@ -137,6 +137,7 @@ QueryCursor.prototype._read = function() { * * @param {Function} fn * @return {QueryCursor} + * @memberOf QueryCursor * @api public * @method map */ From 0354bb50ff177673eb6607eeee0aee6ea6ea9f70 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 16:09:22 +0200 Subject: [PATCH 13/43] style: change jsdoc tag "memberOf" to point to the correct member for "QueryCursor.prototype[Symbol.asyncIterator]" --- lib/cursor/QueryCursor.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/cursor/QueryCursor.js b/lib/cursor/QueryCursor.js index 6327dd4dc9c..663973405ac 100644 --- a/lib/cursor/QueryCursor.js +++ b/lib/cursor/QueryCursor.js @@ -321,7 +321,7 @@ QueryCursor.prototype._transformForAsyncIterator = function() { * support async iterators. * * @method Symbol.asyncIterator - * @memberOf Query + * @memberOf QueryCursor * @instance * @api public */ From 48beee17d4c4534a6f7ddfbf37112eb1e428692a Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 16:11:02 +0200 Subject: [PATCH 14/43] style: add jsdoc tag "memberOf" to "AggregationCursor.prototype.map" --- lib/cursor/AggregationCursor.js | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/cursor/AggregationCursor.js b/lib/cursor/AggregationCursor.js index 02cafc81e0c..72192757b04 100644 --- a/lib/cursor/AggregationCursor.js +++ b/lib/cursor/AggregationCursor.js @@ -132,6 +132,7 @@ if (Symbol.asyncIterator != null) { * * @param {Function} fn * @return {AggregationCursor} + * @memberOf AggregationCursor * @api public * @method map */ From 764612559ff5e2fc18c7353b8cec4d5e39c0d7de Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 16:12:38 +0200 Subject: [PATCH 15/43] style: properly set jsdoc tag "function" for "SchemaType.prototype.castFunction" --- lib/schematype.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/schematype.js b/lib/schematype.js index 53a687370d4..346f5bd51d4 100644 --- a/lib/schematype.js +++ b/lib/schematype.js @@ -241,7 +241,7 @@ SchemaType.cast = function cast(caster) { * @return {Function} * @static * @receiver SchemaType - * @function cast + * @function castFunction * @api public */ From 82a8c03c5f3f74899bbfcdf642031115a7a712d4 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 16:56:01 +0200 Subject: [PATCH 16/43] style: remove and add some jsdoc tags for "SchemaType.prototype.castFunction" --- lib/schematype.js | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/lib/schematype.js b/lib/schematype.js index 346f5bd51d4..6f9f05f4c7c 100644 --- a/lib/schematype.js +++ b/lib/schematype.js @@ -239,9 +239,7 @@ SchemaType.cast = function cast(caster) { * * @param {Function|false} caster Function that casts arbitrary values to this type, or throws an error if casting failed * @return {Function} - * @static - * @receiver SchemaType - * @function castFunction + * @memberOf SchemaType * @api public */ From cb8e66aa502e1e40a6a642ec3daef2a7b9860ef3 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 17:01:38 +0200 Subject: [PATCH 17/43] style: move jsdoc comment to proper function ("DocumentArrayPath.set") This also changes the description for the parameters to match "SchemaType.set" and not cause bad formatting Also upates the return type to "void" --- lib/schema/documentarray.js | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/lib/schema/documentarray.js b/lib/schema/documentarray.js index 4fd05fbe6aa..b8558cf70af 100644 --- a/lib/schema/documentarray.js +++ b/lib/schema/documentarray.js @@ -572,6 +572,12 @@ function scopePaths(array, fields, init) { return hasKeys && selected || undefined; } +/*! + * ignore + */ + +DocumentArrayPath.defaultOptions = {}; + /** * Sets a default option for all DocumentArray instances. * @@ -580,16 +586,14 @@ function scopePaths(array, fields, init) { * // Make all numbers have option `min` equal to 0. * mongoose.Schema.DocumentArray.set('_id', false); * - * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option - * @return {undefined} + * @param {String} option The name of the option you'd like to set (e.g. trim, lowercase, etc...) + * @param {*} value The value of the option you'd like to set. + * @return {void} * @function set * @static * @api public */ -DocumentArrayPath.defaultOptions = {}; - DocumentArrayPath.set = SchemaType.set; /*! From 953853f46647cba203f576e08883cc44da61f844 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 17:03:34 +0200 Subject: [PATCH 18/43] style: replace all "@param {*}" with "@param {Any}" to match other cases --- lib/schema/SubdocumentPath.js | 2 +- lib/schema/array.js | 2 +- lib/schema/boolean.js | 2 +- lib/schema/buffer.js | 2 +- lib/schema/date.js | 2 +- lib/schema/decimal128.js | 2 +- lib/schema/documentarray.js | 2 +- lib/schema/mixed.js | 2 +- lib/schema/number.js | 2 +- lib/schema/objectid.js | 2 +- lib/schema/string.js | 2 +- lib/schematype.js | 2 +- 12 files changed, 12 insertions(+), 12 deletions(-) diff --git a/lib/schema/SubdocumentPath.js b/lib/schema/SubdocumentPath.js index 94a8c588628..30dd77b78d3 100644 --- a/lib/schema/SubdocumentPath.js +++ b/lib/schema/SubdocumentPath.js @@ -323,7 +323,7 @@ SubdocumentPath.prototype.discriminator = function(name, schema, options) { * mongoose.Schema.Embedded.set('required', true); * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/array.js b/lib/schema/array.js index 6874907e9ee..1a36b16663c 100644 --- a/lib/schema/array.js +++ b/lib/schema/array.js @@ -162,7 +162,7 @@ SchemaArray.defaultOptions = {}; * new User({ }).validateSync().errors.test.message; // Path `test` is required. * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @api public diff --git a/lib/schema/boolean.js b/lib/schema/boolean.js index df67452c0c6..75139c47dce 100644 --- a/lib/schema/boolean.js +++ b/lib/schema/boolean.js @@ -56,7 +56,7 @@ SchemaBoolean._cast = castBoolean; * new Order({ }).isPaid; // false * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/buffer.js b/lib/schema/buffer.js index 5b7679e62f2..37364d5b3cb 100644 --- a/lib/schema/buffer.js +++ b/lib/schema/buffer.js @@ -61,7 +61,7 @@ SchemaBuffer._checkRequired = v => !!(v && v.length); * new User({ }).validateSync().errors.test.message; // Path `test` is required. * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/date.js b/lib/schema/date.js index b26310d43e9..4bc30d07c2c 100644 --- a/lib/schema/date.js +++ b/lib/schema/date.js @@ -61,7 +61,7 @@ SchemaDate._cast = castDate; * new User({ }).validateSync().errors.test.message; // Path `test` is required. * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/decimal128.js b/lib/schema/decimal128.js index 3323df4e094..d7c620dbe57 100644 --- a/lib/schema/decimal128.js +++ b/lib/schema/decimal128.js @@ -57,7 +57,7 @@ Decimal128._cast = castDecimal128; * new User({ }).validateSync().errors.test.message; // Path `test` is required. * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/documentarray.js b/lib/schema/documentarray.js index b8558cf70af..7a3bdd48c4a 100644 --- a/lib/schema/documentarray.js +++ b/lib/schema/documentarray.js @@ -587,7 +587,7 @@ DocumentArrayPath.defaultOptions = {}; * mongoose.Schema.DocumentArray.set('_id', false); * * @param {String} option The name of the option you'd like to set (e.g. trim, lowercase, etc...) - * @param {*} value The value of the option you'd like to set. + * @param {Any} value The value of the option you'd like to set. * @return {void} * @function set * @static diff --git a/lib/schema/mixed.js b/lib/schema/mixed.js index 4b236eec786..7b75165b4d3 100644 --- a/lib/schema/mixed.js +++ b/lib/schema/mixed.js @@ -85,7 +85,7 @@ Mixed.get = SchemaType.get; * new User({ }).validateSync().errors.test.message; // Path `test` is required. * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/number.js b/lib/schema/number.js index dff0c02430d..7b9bd3796b1 100644 --- a/lib/schema/number.js +++ b/lib/schema/number.js @@ -58,7 +58,7 @@ SchemaNumber.get = SchemaType.get; * new Order({ amount: -10 }).validateSync().errors.amount.message; // Path `amount` must be larger than 0. * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/objectid.js b/lib/schema/objectid.js index 09a11f716ac..51d7e717bd1 100644 --- a/lib/schema/objectid.js +++ b/lib/schema/objectid.js @@ -85,7 +85,7 @@ ObjectId.get = SchemaType.get; * new Order({ }).validateSync().errors.userId.message; // Path `userId` is required. * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/string.js b/lib/schema/string.js index 3e818d660a1..2410fcb40b5 100644 --- a/lib/schema/string.js +++ b/lib/schema/string.js @@ -134,7 +134,7 @@ SchemaString.get = SchemaType.get; * new User({ name: ' John Doe ' }).name; // 'John Doe' * * @param {String} option - The option you'd like to set the value for - * @param {*} value - value for option + * @param {Any} value - value for option * @return {undefined} * @function set * @static diff --git a/lib/schematype.js b/lib/schematype.js index 6f9f05f4c7c..33898e95760 100644 --- a/lib/schematype.js +++ b/lib/schematype.js @@ -277,7 +277,7 @@ SchemaType.prototype.cast = function cast() { * mongoose.SchemaTypes.String.set('trim', true); * * @param {String} option The name of the option you'd like to set (e.g. trim, lowercase, etc...) - * @param {*} value The value of the option you'd like to set. + * @param {Any} value The value of the option you'd like to set. * @return {void} * @static * @receiver SchemaType From e57594c7a72dc21f91d3fbda2742cf0132e03042 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 17:08:30 +0200 Subject: [PATCH 19/43] style: remove "- " before description to be more consistent This also sometimes somehow messes-up the documentation styling --- lib/helpers/query/castUpdate.js | 8 ++++---- lib/query.js | 2 +- lib/schema/SubdocumentPath.js | 4 ++-- lib/schema/array.js | 4 ++-- lib/schema/boolean.js | 6 +++--- lib/schema/buffer.js | 4 ++-- lib/schema/date.js | 4 ++-- lib/schema/decimal128.js | 4 ++-- lib/schema/documentarray.js | 6 +++--- lib/schema/mixed.js | 4 ++-- lib/schema/number.js | 4 ++-- lib/schema/objectid.js | 4 ++-- lib/schema/string.js | 4 ++-- 13 files changed, 29 insertions(+), 29 deletions(-) diff --git a/lib/helpers/query/castUpdate.js b/lib/helpers/query/castUpdate.js index 9c4d29b6569..03566460ab5 100644 --- a/lib/helpers/query/castUpdate.js +++ b/lib/helpers/query/castUpdate.js @@ -155,12 +155,12 @@ function castPipelineOperator(op, val) { * 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} obj part of a query + * @param {String} op the atomic operator ($pull, $set, etc) * @param {Object} options * @param {Boolean|String} [options.strict] * @param {Query} context - * @param {String} pref - path prefix (internal only) + * @param {String} pref path prefix (internal only) * @return {Bool} true if this path has keys to update * @api private */ @@ -451,7 +451,7 @@ const overwriteOps = { * * @param {SchemaType} schema * @param {Object} val - * @param {String} op - the atomic operator ($pull, $set, etc) + * @param {String} op the atomic operator ($pull, $set, etc) * @param {String} $conditional * @param {Query} context * @api private diff --git a/lib/query.js b/lib/query.js index 291c17fb727..9efc3480dd3 100644 --- a/lib/query.js +++ b/lib/query.js @@ -3865,7 +3865,7 @@ function _getOption(query, option, def) { /*! * Override mquery.prototype._findAndModify to provide casting etc. * - * @param {String} type - either "remove" or "update" + * @param {String} type either "remove" or "update" * @param {Function} callback * @api private */ diff --git a/lib/schema/SubdocumentPath.js b/lib/schema/SubdocumentPath.js index 30dd77b78d3..1b68d5c47b0 100644 --- a/lib/schema/SubdocumentPath.js +++ b/lib/schema/SubdocumentPath.js @@ -322,8 +322,8 @@ SubdocumentPath.prototype.discriminator = function(name, schema, options) { * // Make all numbers have option `min` equal to 0. * mongoose.Schema.Embedded.set('required', true); * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/array.js b/lib/schema/array.js index 1a36b16663c..a96de5f7be1 100644 --- a/lib/schema/array.js +++ b/lib/schema/array.js @@ -161,8 +161,8 @@ SchemaArray.defaultOptions = {}; * const User = mongoose.model('User', new Schema({ test: Array })); * new User({ }).validateSync().errors.test.message; // Path `test` is required. * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @api public diff --git a/lib/schema/boolean.js b/lib/schema/boolean.js index 75139c47dce..5eff2c5605d 100644 --- a/lib/schema/boolean.js +++ b/lib/schema/boolean.js @@ -55,8 +55,8 @@ SchemaBoolean._cast = castBoolean; * const Order = mongoose.model('Order', new Schema({ isPaid: Boolean })); * new Order({ }).isPaid; // false * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @static @@ -189,7 +189,7 @@ Object.defineProperty(SchemaBoolean, 'convertToFalse', { * Casts to boolean * * @param {Object} value - * @param {Object} model - this value is optional + * @param {Object} model this value is optional * @api private */ diff --git a/lib/schema/buffer.js b/lib/schema/buffer.js index 37364d5b3cb..abe0859314f 100644 --- a/lib/schema/buffer.js +++ b/lib/schema/buffer.js @@ -60,8 +60,8 @@ SchemaBuffer._checkRequired = v => !!(v && v.length); * const User = mongoose.model('User', new Schema({ test: Buffer })); * new User({ }).validateSync().errors.test.message; // Path `test` is required. * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/date.js b/lib/schema/date.js index 4bc30d07c2c..4edc764210a 100644 --- a/lib/schema/date.js +++ b/lib/schema/date.js @@ -60,8 +60,8 @@ SchemaDate._cast = castDate; * const User = mongoose.model('User', new Schema({ test: Date })); * new User({ }).validateSync().errors.test.message; // Path `test` is required. * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/decimal128.js b/lib/schema/decimal128.js index d7c620dbe57..6ac87416fe6 100644 --- a/lib/schema/decimal128.js +++ b/lib/schema/decimal128.js @@ -56,8 +56,8 @@ Decimal128._cast = castDecimal128; * const User = mongoose.model('User', new Schema({ test: mongoose.Decimal128 })); * new User({ }).validateSync().errors.test.message; // Path `test` is required. * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/documentarray.js b/lib/schema/documentarray.js index 7a3bdd48c4a..ea35736cc33 100644 --- a/lib/schema/documentarray.js +++ b/lib/schema/documentarray.js @@ -536,9 +536,9 @@ DocumentArrayPath.prototype.applyGetters = function(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 + * @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 */ function scopePaths(array, fields, init) { diff --git a/lib/schema/mixed.js b/lib/schema/mixed.js index 7b75165b4d3..6fbaba094b6 100644 --- a/lib/schema/mixed.js +++ b/lib/schema/mixed.js @@ -84,8 +84,8 @@ Mixed.get = SchemaType.get; * const User = mongoose.model('User', new Schema({ test: mongoose.Mixed })); * new User({ }).validateSync().errors.test.message; // Path `test` is required. * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/number.js b/lib/schema/number.js index 7b9bd3796b1..bbee66df799 100644 --- a/lib/schema/number.js +++ b/lib/schema/number.js @@ -57,8 +57,8 @@ SchemaNumber.get = SchemaType.get; * const Order = mongoose.model('Order', new Schema({ amount: Number })); * new Order({ amount: -10 }).validateSync().errors.amount.message; // Path `amount` must be larger than 0. * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/objectid.js b/lib/schema/objectid.js index 51d7e717bd1..56d09ed37d1 100644 --- a/lib/schema/objectid.js +++ b/lib/schema/objectid.js @@ -84,8 +84,8 @@ ObjectId.get = SchemaType.get; * const Order = mongoose.model('Order', new Schema({ userId: ObjectId })); * new Order({ }).validateSync().errors.userId.message; // Path `userId` is required. * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @static diff --git a/lib/schema/string.js b/lib/schema/string.js index 2410fcb40b5..3febba9c579 100644 --- a/lib/schema/string.js +++ b/lib/schema/string.js @@ -133,8 +133,8 @@ SchemaString.get = SchemaType.get; * const User = mongoose.model('User', new Schema({ name: String })); * new User({ name: ' John Doe ' }).name; // 'John Doe' * - * @param {String} option - The option you'd like to set the value for - * @param {Any} value - value for option + * @param {String} option The option you'd like to set the value for + * @param {Any} value value for option * @return {undefined} * @function set * @static From 1719bf6dc4f1ab77640b8f8d3e12ad94004e9461 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 17:16:27 +0200 Subject: [PATCH 20/43] style: remove extra parameters from "@static" The things that were defined there are set via other things anyway, and many did not even have it set --- lib/error/index.js | 24 ++++++++++++------------ lib/error/messages.js | 2 +- lib/model.js | 2 +- lib/schema.js | 2 +- lib/schema/array.js | 2 +- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/lib/error/index.js b/lib/error/index.js index 4f5b446736f..51d19fa5b6f 100644 --- a/lib/error/index.js +++ b/lib/error/index.js @@ -56,7 +56,7 @@ module.exports = exports = MongooseError; * @see Error.messages #error_messages_MongooseError-messages * @api public * @memberOf Error - * @static messages + * @static */ MongooseError.messages = require('./messages'); @@ -73,7 +73,7 @@ MongooseError.Messages = MongooseError.messages; * * @api public * @memberOf Error - * @static DocumentNotFoundError + * @static */ MongooseError.DocumentNotFoundError = require('./notFound'); @@ -84,7 +84,7 @@ MongooseError.DocumentNotFoundError = require('./notFound'); * * @api public * @memberOf Error - * @static CastError + * @static */ MongooseError.CastError = require('./cast'); @@ -96,7 +96,7 @@ MongooseError.CastError = require('./cast'); * * @api public * @memberOf Error - * @static ValidationError + * @static */ MongooseError.ValidationError = require('./validation'); @@ -131,7 +131,7 @@ MongooseError.ValidationError = require('./validation'); * * @api public * @memberOf Error - * @static ValidatorError + * @static */ MongooseError.ValidatorError = require('./validator'); @@ -143,7 +143,7 @@ MongooseError.ValidatorError = require('./validator'); * * @api public * @memberOf Error - * @static VersionError + * @static */ MongooseError.VersionError = require('./version'); @@ -155,7 +155,7 @@ MongooseError.VersionError = require('./version'); * * @api public * @memberOf Error - * @static ParallelSaveError + * @static */ MongooseError.ParallelSaveError = require('./parallelSave'); @@ -166,7 +166,7 @@ MongooseError.ParallelSaveError = require('./parallelSave'); * * @api public * @memberOf Error - * @static OverwriteModelError + * @static */ MongooseError.OverwriteModelError = require('./overwriteModel'); @@ -176,7 +176,7 @@ MongooseError.OverwriteModelError = require('./overwriteModel'); * * @api public * @memberOf Error - * @static MissingSchemaError + * @static */ MongooseError.MissingSchemaError = require('./missingSchema'); @@ -187,7 +187,7 @@ MongooseError.MissingSchemaError = require('./missingSchema'); * * @api public * @memberOf Error - * @static MongooseServerSelectionError + * @static */ MongooseError.MongooseServerSelectionError = require('./serverSelection'); @@ -198,7 +198,7 @@ MongooseError.MongooseServerSelectionError = require('./serverSelection'); * * @api public * @memberOf Error - * @static DivergentArrayError + * @static */ MongooseError.DivergentArrayError = require('./divergentArray'); @@ -210,7 +210,7 @@ MongooseError.DivergentArrayError = require('./divergentArray'); * * @api public * @memberOf Error - * @static StrictModeError + * @static */ MongooseError.StrictModeError = require('./strict'); diff --git a/lib/error/messages.js b/lib/error/messages.js index ac0294a39a4..717340acab2 100644 --- a/lib/error/messages.js +++ b/lib/error/messages.js @@ -16,7 +16,7 @@ * * Click the "show code" link below to see all defaults. * - * @static messages + * @static * @receiver MongooseError * @api public */ diff --git a/lib/model.js b/lib/model.js index c66828b464f..4b69dea9554 100644 --- a/lib/model.js +++ b/lib/model.js @@ -212,7 +212,7 @@ Model.prototype.baseModelName; * @api public * @fires error whenever any query or model function errors * @memberOf Model - * @static events + * @static */ Model.events; diff --git a/lib/schema.js b/lib/schema.js index 5177e5c9590..83ea482cd30 100644 --- a/lib/schema.js +++ b/lib/schema.js @@ -1874,7 +1874,7 @@ Schema.prototype.get = function(key) { * The allowed index types * * @receiver Schema - * @static indexTypes + * @static * @api public */ diff --git a/lib/schema/array.js b/lib/schema/array.js index a96de5f7be1..33218d3a0aa 100644 --- a/lib/schema/array.js +++ b/lib/schema/array.js @@ -138,7 +138,7 @@ SchemaArray.schemaName = 'Array'; * * - `castNonArrays`: `true` by default. If `false`, Mongoose will throw a CastError when a value isn't an array. If `true`, Mongoose will wrap the provided value in an array before casting. * - * @static options + * @static * @api public */ From 590f0ff611b408f133ed764c64252a55f34f1ead Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 17:38:54 +0200 Subject: [PATCH 21/43] style: move jsdoc comment to proper function ("SubdocumentPath.set") This also changes the description for the parameters to match "SubdocumentPath.set" and not cause bad formatting Also upates the return type to "void" --- lib/schema/SubdocumentPath.js | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/lib/schema/SubdocumentPath.js b/lib/schema/SubdocumentPath.js index 1b68d5c47b0..748abd8e923 100644 --- a/lib/schema/SubdocumentPath.js +++ b/lib/schema/SubdocumentPath.js @@ -314,24 +314,28 @@ SubdocumentPath.prototype.discriminator = function(name, schema, options) { return this.caster.discriminators[name]; }; +/*! + * ignore + */ + +SubdocumentPath.defaultOptions = {}; + /** * Sets a default option for all SubdocumentPath instances. * * #### Example: * * // Make all numbers have option `min` equal to 0. - * mongoose.Schema.Embedded.set('required', true); + * mongoose.Schema.SubdocumentPath.set('required', true); * * @param {String} option The option you'd like to set the value for * @param {Any} value value for option - * @return {undefined} + * @return {void} * @function set * @static * @api public */ -SubdocumentPath.defaultOptions = {}; - SubdocumentPath.set = SchemaType.set; /*! From dbc078b3397fd544a4aa7bfda94a57c21f37adef Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 17:40:20 +0200 Subject: [PATCH 22/43] chore: upgrade "dox" to "0.8.1" --- docs/source/api.js | 24 ++++++++++++------------ package.json | 2 +- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index e51d6a24f70..3543fb3d423 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -101,16 +101,8 @@ function parse() { case 'property': ctx.type = 'property'; - // transform "tag" properties to how the way before tag 4.5 - // in 4.4 something like "{Connection} connection" or "{Array} connections" was put out, now "tag" contains different properties - // which would look like "tag = { type: 'property', types: ['Connection'], name: 'connection' }" - // or "tag = { type: 'property', types: ['Array'], name: 'connections' }" - let str; - if (tag.name.length > 0) { - str = "{" + tag.types.join(' ') + "} " + tag.name; - } else { - str = tag.types.join(' '); - } + // somewhere since 6.0 the "string" property came back, which was gone with 4.5 + let str = tag.string; const match = str.match(/^{\w+}/); if (match != null) { @@ -126,14 +118,18 @@ function parse() { case 'static': ctx.type = 'property'; ctx.static = true; - ctx.name = tag.string; + // dont take "string" as "name" from here, because jsdoc definitions of "static" do not have parameters, also its defined elsewhere anyway + // ctx.name = tag.string; ctx.string = `${data.name}.${ctx.name}`; break; case 'function': ctx.type = 'function'; ctx.static = true; ctx.name = tag.string; - ctx.string = `${data.name}.${ctx.name}()`; + ctx.string = `${data.name}.${ctx.name}`; + // extra parameter to make function definitions independant of where "@function" is defined + // like "@static" could have overwritten "ctx.string" again if defined after "@function" + ctx.isFunction = true; break; case 'return': tag.return = tag.description ? @@ -176,6 +172,10 @@ function parse() { } } + if (ctx.isFunction && !ctx.string.endsWith("()")) { + ctx.string = ctx.string + "()"; + } + if (/\.prototype[^.]/.test(ctx.string)) { ctx.string = `${ctx.constructor}.prototype.${ctx.name}`; } diff --git a/package.json b/package.json index 1791f3f1b1e..9558e63dc9b 100644 --- a/package.json +++ b/package.json @@ -42,7 +42,7 @@ "buffer": "^5.6.0", "cheerio": "1.0.0-rc.11", "crypto-browserify": "3.12.0", - "dox": "0.5.3", + "dox": "0.8.1", "eslint": "8.16.0", "eslint-plugin-mocha-no-only": "1.1.1", "highlight.js": "11.5.1", From 728d967c6a58fa92084fe958103bfd1624d6fcb4 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 17:41:30 +0200 Subject: [PATCH 23/43] chore: upgrade "dox" to "0.9.1" --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 9558e63dc9b..3670022a7a2 100644 --- a/package.json +++ b/package.json @@ -42,7 +42,7 @@ "buffer": "^5.6.0", "cheerio": "1.0.0-rc.11", "crypto-browserify": "3.12.0", - "dox": "0.8.1", + "dox": "0.9.1", "eslint": "8.16.0", "eslint-plugin-mocha-no-only": "1.1.1", "highlight.js": "11.5.1", From 96e1ffd63c25761e56a7b6217a4570e8b9eb106a Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 17:43:08 +0200 Subject: [PATCH 24/43] chore(docs/source/api): change to use "isFunction" instead of directly adding "()" --- docs/source/api.js | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index 3543fb3d423..3e841b19347 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -157,18 +157,20 @@ function parse() { case 'method': ctx.type = 'method'; ctx.name = tag.string; - ctx.string = `${ctx.constructor}.prototype.${ctx.name}()`; + ctx.string = `${ctx.constructor}.prototype.${ctx.name}`; + ctx.isFunction = true; break; case 'memberOf': ctx.constructor = tag.parent; ctx.string = `${ctx.constructor}.prototype.${ctx.name}`; if (ctx.type === 'method') { - ctx.string += '()'; + ctx.isFunction = true; } break; case 'constructor': - ctx.string = tag.string + '()'; + ctx.string = tag.string; ctx.name = tag.string; + ctx.isFunction = true; } } From cfe72488bd28b2c818ef87e86a87240523687b4b Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 17:47:26 +0200 Subject: [PATCH 25/43] chore(docs/source/api): use "ctx.constructor" over "data.name" for "function" and "static" This fixes static "Schematype" properties to be in a different case than instance properties --- docs/source/api.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index 3e841b19347..685386653f4 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -120,13 +120,13 @@ function parse() { ctx.static = true; // dont take "string" as "name" from here, because jsdoc definitions of "static" do not have parameters, also its defined elsewhere anyway // ctx.name = tag.string; - ctx.string = `${data.name}.${ctx.name}`; + ctx.string = `${ctx.constructor}.${ctx.name}`; break; case 'function': ctx.type = 'function'; ctx.static = true; ctx.name = tag.string; - ctx.string = `${data.name}.${ctx.name}`; + ctx.string = `${ctx.constructor}.${ctx.name}`; // extra parameter to make function definitions independant of where "@function" is defined // like "@static" could have overwritten "ctx.string" again if defined after "@function" ctx.isFunction = true; From 39a02a18d1840d68868b54acd91d392e9640088c Mon Sep 17 00:00:00 2001 From: hasezoey Date: Thu, 30 Jun 2022 18:13:26 +0200 Subject: [PATCH 26/43] chore(docs/source/api): remove console.log of the "ctx" --- docs/source/api.js | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index 685386653f4..0ac1a9e69b3 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -194,9 +194,6 @@ function parse() { ctx.description = prop.description.full. replace(/
/ig, ' '). replace(/>/ig, '>'); - if (ctx.description.includes('function capitalize')) { - console.log('\n\n-------\n\n', ctx); - } ctx.description = md.parse(ctx.description); data.props.push(ctx); From 407fe6194e4f81aba170b6b88dd4b987c8bdb789 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sat, 2 Jul 2022 16:23:45 +0200 Subject: [PATCH 27/43] style: update "syncIndexes" jsdoc to only have "Promise" as return type for "connection" and "mongoose" --- lib/connection.js | 2 +- lib/index.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/connection.js b/lib/connection.js index 11057ea4b8a..b8a25c92669 100644 --- a/lib/connection.js +++ b/lib/connection.js @@ -1452,7 +1452,7 @@ Connection.prototype.setClient = function setClient(client) { * * @param {Object} options * @param {Boolean} options.continueOnError `false` by default. If set to `true`, mongoose will not throw an error if one model syncing failed, and will return an object where the keys are the names of the models, and the values are the results/errors for each model. - * @return {Promise|undefined} Returns `undefined` if callback is specified, returns a promise if no callback, when the Promise resolves the value is a list of the dropped indexes. + * @return {Promise} Returns a Promise, when the Promise resolves the value is a list of the dropped indexes. */ Connection.prototype.syncIndexes = async function syncIndexes(options = {}) { const result = {}; diff --git a/lib/index.js b/lib/index.js index cda6e724d12..89c5101f032 100644 --- a/lib/index.js +++ b/lib/index.js @@ -1046,7 +1046,7 @@ Mongoose.prototype.isObjectIdOrHexString = function(v) { * * @param {Object} options * @param {Boolean} options.continueOnError `false` by default. If set to `true`, mongoose will not throw an error if one model syncing failed, and will return an object where the keys are the names of the models, and the values are the results/errors for each model. - * @return {Promise|undefined} Returns `undefined` if callback is specified, returns a promise if no callback, when the Promise resolves the value is a list of the dropped indexes. + * @return {Promise} Returns a Promise, when the Promise resolves the value is a list of the dropped indexes. */ Mongoose.prototype.syncIndexes = function(options) { const _mongoose = this instanceof Mongoose ? this : mongoose; From 1384f274c260c081c9266730b027d0efdf6fb00e Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 11:58:52 +0200 Subject: [PATCH 28/43] chore(docs/source/api): basic handle jsdoc "@instance" tag also warn if both a static and instance are found --- docs/source/api.js | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/source/api.js b/docs/source/api.js index 2da22edd2fb..b176f55e5ba 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -174,9 +174,17 @@ function parse() { ctx.string = tag.string; ctx.name = tag.string; ctx.isFunction = true; + break; + case 'instance': + ctx.isInstance = true; + break; } } + if (ctx.isInstance && ctx.static) { + console.warn(`Property "${ctx.name}" in "${ctx.constructor}" has both instance and static JSDOC markings (most likely both @instance and @static)! (File: "${props.file}")`); + } + if (ctx.isFunction && !ctx.string.endsWith("()")) { ctx.string = ctx.string + "()"; } From a0062148ba450028a51ddab6ab5d39698b33aa2e Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 12:00:02 +0200 Subject: [PATCH 29/43] chore(docs/source/api): rename "ctx.static" to "ctx.isStatic" --- docs/source/api.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index b176f55e5ba..93ee6bba2fd 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -120,14 +120,14 @@ function parse() { break; case 'static': ctx.type = 'property'; - ctx.static = true; + ctx.isStatic = true; // dont take "string" as "name" from here, because jsdoc definitions of "static" do not have parameters, also its defined elsewhere anyway // ctx.name = tag.string; ctx.string = `${ctx.constructor}.${ctx.name}`; break; case 'function': ctx.type = 'function'; - ctx.static = true; + ctx.isStatic = true; ctx.name = tag.string; ctx.string = `${ctx.constructor}.${ctx.name}`; // extra parameter to make function definitions independant of where "@function" is defined @@ -181,7 +181,7 @@ function parse() { } } - if (ctx.isInstance && ctx.static) { + if (ctx.isInstance && ctx.isStatic) { console.warn(`Property "${ctx.name}" in "${ctx.constructor}" has both instance and static JSDOC markings (most likely both @instance and @static)! (File: "${props.file}")`); } From 17c7e6366bc95a27dc4b54e7ad8ece3d5858c288 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 12:42:28 +0200 Subject: [PATCH 30/43] chore(docs/source/api): move setting of "ctx.string" to after the tags loop This will make setting "ctx.string" consistently and should make it independent of tag order (Also thanks to the previous commit warns against both "instance" and "static") --- docs/source/api.js | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index 93ee6bba2fd..3426c17d214 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -96,6 +96,19 @@ function parse() { } const ctx = prop.ctx || {}; + + // somehow in "dox", it is named "receiver" sometimes, not "constructor" + // this is used as a fall-back if the handling below does not overwrite it + if ("receiver" in ctx) { + ctx.constructor = ctx.receiver; + delete ctx.receiver; + } + + // in some cases "dox" has "ctx.constructor" defined but set to "undefined", which will later be used for setting "ctx.string" + if ("constructor" in ctx && ctx.constructor === undefined) { + ctx.constructorWasUndefined = true; + } + for (const tag of prop.tags) { switch (tag.type) { case 'receiver': @@ -113,7 +126,6 @@ function parse() { str = str.replace(/^{\w+}\s*/, ''); } ctx.name = str; - ctx.string = `${ctx.constructor}.prototype.${ctx.name}`; break; case 'type': ctx.type = Array.isArray(tag.types) ? tag.types.join('|') : tag.types; @@ -123,13 +135,11 @@ function parse() { ctx.isStatic = true; // dont take "string" as "name" from here, because jsdoc definitions of "static" do not have parameters, also its defined elsewhere anyway // ctx.name = tag.string; - ctx.string = `${ctx.constructor}.${ctx.name}`; break; case 'function': ctx.type = 'function'; ctx.isStatic = true; ctx.name = tag.string; - ctx.string = `${ctx.constructor}.${ctx.name}`; // extra parameter to make function definitions independant of where "@function" is defined // like "@static" could have overwritten "ctx.string" again if defined after "@function" ctx.isFunction = true; @@ -160,12 +170,10 @@ function parse() { case 'method': ctx.type = 'method'; ctx.name = tag.string; - ctx.string = `${ctx.constructor}.prototype.${ctx.name}`; ctx.isFunction = true; break; case 'memberOf': ctx.constructor = tag.parent; - ctx.string = `${ctx.constructor}.prototype.${ctx.name}`; if (ctx.type === 'method') { ctx.isFunction = true; } @@ -185,6 +193,15 @@ function parse() { console.warn(`Property "${ctx.name}" in "${ctx.constructor}" has both instance and static JSDOC markings (most likely both @instance and @static)! (File: "${props.file}")`); } + // the following if-else-if statement is in this order, because there are more "instance" methods thans static + // the following condition will be true if "isInstance = true" or if "isInstance = false && isStatic = false" AND "ctx.string" are empty or not defined + // if "isStatic" and "isInstance" are falsy and "ctx.string" is not falsy, then rely on the "ctx.string" set by "dox" + if (ctx.isInstance || (!ctx.isStatic && !ctx.isInstance && (!ctx.string || ctx.constructorWasUndefined))) { + ctx.string = `${ctx.constructor}.prototype.${ctx.name}`; + } else if (ctx.isStatic) { + ctx.string = `${ctx.constructor}.${ctx.name}`; + } + if (ctx.isFunction && !ctx.string.endsWith("()")) { ctx.string = ctx.string + "()"; } From 73f3400bc9ffc43dff87da71dc8c6e72af3d6e1c Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 12:43:31 +0200 Subject: [PATCH 31/43] style: update jsdoc "memberOf" for "MongooseMap.prototype.$isMongooseMap" to reflect actual name --- lib/types/map.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/types/map.js b/lib/types/map.js index 1cfc98d8f9a..4cea656c206 100644 --- a/lib/types/map.js +++ b/lib/types/map.js @@ -275,7 +275,7 @@ Object.defineProperty(MongooseMap.prototype, '$__schemaType', { * * @api public * @property $isMongooseMap - * @memberOf Map + * @memberOf MongooseMap * @instance */ From 6c0e316819760bfd604fc68edb32879e93e01bc1 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 12:55:02 +0200 Subject: [PATCH 32/43] style: set proper jsdoc "memberOf" path for "MongooseBuffer.mixin.*" and add "@static" --- lib/types/buffer.js | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/lib/types/buffer.js b/lib/types/buffer.js index ca3787cc6f0..f2d51794df4 100644 --- a/lib/types/buffer.js +++ b/lib/types/buffer.js @@ -70,7 +70,8 @@ MongooseBuffer.mixin = { * * @api private * @property _subtype - * @memberOf MongooseBuffer + * @memberOf MongooseBuffer.mixin + * @static */ _subtype: undefined, @@ -80,7 +81,8 @@ MongooseBuffer.mixin = { * * @api private * @method _markModified - * @memberOf MongooseBuffer + * @memberOf MongooseBuffer.mixin + * @static */ _markModified: function() { @@ -97,7 +99,8 @@ MongooseBuffer.mixin = { * * @api public * @method write - * @memberOf MongooseBuffer + * @memberOf MongooseBuffer.mixin + * @static */ write: function() { @@ -120,7 +123,8 @@ MongooseBuffer.mixin = { * @return {Number} The number of bytes copied. * @param {Buffer} target * @method copy - * @memberOf MongooseBuffer + * @memberOf MongooseBuffer.mixin + * @static */ copy: function(target) { From da57bf2fc5064013afbc17cdd5c5996aa1ddcd3b Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 13:09:44 +0200 Subject: [PATCH 33/43] chore(docs/source/api): remove redundant setting of "isFunction" in "memberOf" handling --- docs/source/api.js | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index 3426c17d214..becb26c548a 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -174,9 +174,6 @@ function parse() { break; case 'memberOf': ctx.constructor = tag.parent; - if (ctx.type === 'method') { - ctx.isFunction = true; - } break; case 'constructor': ctx.string = tag.string; @@ -202,7 +199,7 @@ function parse() { ctx.string = `${ctx.constructor}.${ctx.name}`; } - if (ctx.isFunction && !ctx.string.endsWith("()")) { + if ((ctx.isFunction || ctx.type === "method") && !ctx.string.endsWith("()")) { ctx.string = ctx.string + "()"; } From 9f73623676894b11d1a182431d37f37203b601bb Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 13:11:32 +0200 Subject: [PATCH 34/43] chore(docs/source/api): add more comments explaining what some things do --- docs/source/api.js | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/api.js b/docs/source/api.js index becb26c548a..72202ab8232 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -199,15 +199,17 @@ function parse() { ctx.string = `${ctx.constructor}.${ctx.name}`; } + // add "()" to the end of the string if function if ((ctx.isFunction || ctx.type === "method") && !ctx.string.endsWith("()")) { ctx.string = ctx.string + "()"; } + // fixing up "something.prototypemissingdot" to "something.prototype.missingdot" if (/\.prototype[^.]/.test(ctx.string)) { ctx.string = `${ctx.constructor}.prototype.${ctx.name}`; } - // Backwards compat + // Backwards compat anchors if (typeof ctx.constructor === 'string') { ctx.anchorId = `${ctx.constructor.toLowerCase()}_${ctx.constructor}-${ctx.name}`; } else if (typeof ctx.receiver === 'string') { From fcb2bfc2ed35190da62c251d99c1dc60aa9565e4 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 13:21:51 +0200 Subject: [PATCH 35/43] chore(docs/source/api): add "void" to types in return, so it does not result in a empty field --- docs/source/api.js | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/api.js b/docs/source/api.js index 72202ab8232..8202dc35417 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -148,6 +148,12 @@ function parse() { tag.return = tag.description ? md.parse(tag.description).replace(/^

/, '').replace(/<\/p>$/, '') : ''; + + // dox does not add "void" / "undefined" to types, so in the documentation it would result in a empty "«»" + if (tag.string.includes('void') || tag.string.includes('undefined')) { + tag.types.push("void"); + } + ctx.return = tag; break; case 'inherits': From cf6ad8870821e59846a126486bc7f1be7a815845 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 13:38:55 +0200 Subject: [PATCH 36/43] chore(docs/source/api): add some jsdoc-typescript types to help remember all values This makes use of https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html and is still fully compatible with plain js --- docs/source/api.js | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/source/api.js b/docs/source/api.js index 8202dc35417..ee506be77d2 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -63,6 +63,21 @@ for (const file of files) { parse(); +/** + * @typedef {Object} PropContext + * @property {boolean} [isStatic] Defines wheter the current property is a static property (not mutually exlusive with "isInstance") + * @property {boolean} [isInstance] Defines wheter the current property is a instance property (not mutually exlusive with "isStatic") + * @property {boolean} [isFunction] Defines wheter the current property is meant to be a function + * @property {string} [constructor] Defines the Constructor (or rather path) the current property is on + * @property {boolean} [constructorWasUndefined] Defined wheter the "constructor" property was defined by "dox", but was set to "undefined" + * @property {string} [type] Defines the type the property is meant to be + * @property {string} [name] Defines the current Properties name + * @property {Object} [return] The full object for a "@return" jsdoc tag + * @property {string} [string] Defines the full string the property will be listed as + * @property {string} [anchorId] Defines the Anchor ID to be used for linking + * @property {string} [description] Defines the Description the property will be listed with + */ + function parse() { for (const props of combinedFiles) { let name = props.file. @@ -94,7 +109,8 @@ function parse() { if (prop.ignore || prop.isPrivate) { continue; } - + + /** @type {PropContext} */ const ctx = prop.ctx || {}; // somehow in "dox", it is named "receiver" sometimes, not "constructor" From ec947f6582ad76592878553c0e873ba69f1dd4d2 Mon Sep 17 00:00:00 2001 From: hasezoey Date: Sun, 3 Jul 2022 13:40:58 +0200 Subject: [PATCH 37/43] chore(docs/source/api): add handling for "@deprecated" and property This currently does not add anything to the final documentation, because i dont know which style it should be --- docs/source/api.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/api.js b/docs/source/api.js index ee506be77d2..a9ee16027ef 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -76,6 +76,7 @@ parse(); * @property {string} [string] Defines the full string the property will be listed as * @property {string} [anchorId] Defines the Anchor ID to be used for linking * @property {string} [description] Defines the Description the property will be listed with + * @property {string} [deprecated] Defines wheter the current Property is signaled as deprecated */ function parse() { @@ -205,6 +206,9 @@ function parse() { case 'instance': ctx.isInstance = true; break; + case 'deprecated': + ctx.deprecated = true; + break; } } From 5d80579b85004d631bc77cea4e485e8737bfadde Mon Sep 17 00:00:00 2001 From: hasezoey Date: Mon, 4 Jul 2022 12:06:54 +0200 Subject: [PATCH 38/43] style: properly escape "@type" type parameters --- lib/options/SchemaArrayOptions.js | 4 ++-- lib/options/SchemaBufferOptions.js | 2 +- lib/options/SchemaDateOptions.js | 6 ++--- lib/options/SchemaDocumentArrayOptions.js | 4 ++-- lib/options/SchemaMapOptions.js | 2 +- lib/options/SchemaNumberOptions.js | 8 +++---- lib/options/SchemaObjectIdOptions.js | 4 ++-- lib/options/SchemaStringOptions.js | 16 ++++++------- lib/options/SchemaSubdocumentOptions.js | 2 +- lib/options/SchemaTypeOptions.js | 28 +++++++++++------------ lib/options/VirtualOptions.js | 22 +++++++++--------- lib/schema/boolean.js | 4 ++-- 12 files changed, 51 insertions(+), 51 deletions(-) diff --git a/lib/options/SchemaArrayOptions.js b/lib/options/SchemaArrayOptions.js index 5cd0733e224..9ea87f3e37c 100644 --- a/lib/options/SchemaArrayOptions.js +++ b/lib/options/SchemaArrayOptions.js @@ -26,7 +26,7 @@ const opts = require('./propertyOptions'); * @api public * @property enum * @memberOf SchemaArrayOptions - * @type Array + * @type {Array} * @instance */ @@ -46,7 +46,7 @@ Object.defineProperty(SchemaArrayOptions.prototype, 'enum', opts); * @api public * @property of * @memberOf SchemaArrayOptions - * @type Function|String + * @type {Function|String} * @instance */ diff --git a/lib/options/SchemaBufferOptions.js b/lib/options/SchemaBufferOptions.js index 96f7f61c35f..377e3566a58 100644 --- a/lib/options/SchemaBufferOptions.js +++ b/lib/options/SchemaBufferOptions.js @@ -25,7 +25,7 @@ const opts = require('./propertyOptions'); * @api public * @property subtype * @memberOf SchemaBufferOptions - * @type Number + * @type {Number} * @instance */ diff --git a/lib/options/SchemaDateOptions.js b/lib/options/SchemaDateOptions.js index bd43a929012..c7d3d4e1044 100644 --- a/lib/options/SchemaDateOptions.js +++ b/lib/options/SchemaDateOptions.js @@ -26,7 +26,7 @@ const opts = require('./propertyOptions'); * @api public * @property min * @memberOf SchemaDateOptions - * @type Date + * @type {Date} * @instance */ @@ -39,7 +39,7 @@ Object.defineProperty(SchemaDateOptions.prototype, 'min', opts); * @api public * @property max * @memberOf SchemaDateOptions - * @type Date + * @type {Date} * @instance */ @@ -58,7 +58,7 @@ Object.defineProperty(SchemaDateOptions.prototype, 'max', opts); * @api public * @property expires * @memberOf SchemaDateOptions - * @type Date + * @type {Date} * @instance */ diff --git a/lib/options/SchemaDocumentArrayOptions.js b/lib/options/SchemaDocumentArrayOptions.js index d12dbebf0ac..b826b87877b 100644 --- a/lib/options/SchemaDocumentArrayOptions.js +++ b/lib/options/SchemaDocumentArrayOptions.js @@ -35,7 +35,7 @@ const opts = require('./propertyOptions'); * @api public * @property excludeIndexes * @memberOf SchemaDocumentArrayOptions - * @type Array + * @type {Array} * @instance */ @@ -55,7 +55,7 @@ Object.defineProperty(SchemaDocumentArrayOptions.prototype, 'excludeIndexes', op * @api public * @property _id * @memberOf SchemaDocumentArrayOptions - * @type Array + * @type {Array} * @instance */ diff --git a/lib/options/SchemaMapOptions.js b/lib/options/SchemaMapOptions.js index af597612ad7..bbabaa0700d 100644 --- a/lib/options/SchemaMapOptions.js +++ b/lib/options/SchemaMapOptions.js @@ -34,7 +34,7 @@ const opts = require('./propertyOptions'); * @api public * @property of * @memberOf SchemaMapOptions - * @type Function|string + * @type {Function|string} * @instance */ diff --git a/lib/options/SchemaNumberOptions.js b/lib/options/SchemaNumberOptions.js index a5e93838893..b052a29baec 100644 --- a/lib/options/SchemaNumberOptions.js +++ b/lib/options/SchemaNumberOptions.js @@ -26,7 +26,7 @@ const opts = require('./propertyOptions'); * @api public * @property min * @memberOf SchemaNumberOptions - * @type Number + * @type {Number} * @instance */ @@ -39,7 +39,7 @@ Object.defineProperty(SchemaNumberOptions.prototype, 'min', opts); * @api public * @property max * @memberOf SchemaNumberOptions - * @type Number + * @type {Number} * @instance */ @@ -61,7 +61,7 @@ Object.defineProperty(SchemaNumberOptions.prototype, 'max', opts); * @api public * @property enum * @memberOf SchemaNumberOptions - * @type Array + * @type {Array} * @instance */ @@ -86,7 +86,7 @@ Object.defineProperty(SchemaNumberOptions.prototype, 'enum', opts); * @api public * @property populate * @memberOf SchemaNumberOptions - * @type Object + * @type {Object} * @instance */ diff --git a/lib/options/SchemaObjectIdOptions.js b/lib/options/SchemaObjectIdOptions.js index 0a9c1b22fcd..fde52adbeca 100644 --- a/lib/options/SchemaObjectIdOptions.js +++ b/lib/options/SchemaObjectIdOptions.js @@ -25,7 +25,7 @@ const opts = require('./propertyOptions'); * @api public * @property auto * @memberOf SchemaObjectIdOptions - * @type Boolean + * @type {Boolean} * @instance */ @@ -50,7 +50,7 @@ Object.defineProperty(SchemaObjectIdOptions.prototype, 'auto', opts); * @api public * @property populate * @memberOf SchemaObjectIdOptions - * @type Object + * @type {Object} * @instance */ diff --git a/lib/options/SchemaStringOptions.js b/lib/options/SchemaStringOptions.js index aee4f6620a0..49836ef13d0 100644 --- a/lib/options/SchemaStringOptions.js +++ b/lib/options/SchemaStringOptions.js @@ -25,7 +25,7 @@ const opts = require('./propertyOptions'); * @api public * @property enum * @memberOf SchemaStringOptions - * @type Array + * @type {Array} * @instance */ @@ -38,7 +38,7 @@ Object.defineProperty(SchemaStringOptions.prototype, 'enum', opts); * @api public * @property match * @memberOf SchemaStringOptions - * @type RegExp + * @type {RegExp} * @instance */ @@ -51,7 +51,7 @@ Object.defineProperty(SchemaStringOptions.prototype, 'match', opts); * @api public * @property lowercase * @memberOf SchemaStringOptions - * @type Boolean + * @type {Boolean} * @instance */ @@ -64,7 +64,7 @@ Object.defineProperty(SchemaStringOptions.prototype, 'lowercase', opts); * @api public * @property trim * @memberOf SchemaStringOptions - * @type Boolean + * @type {Boolean} * @instance */ @@ -77,7 +77,7 @@ Object.defineProperty(SchemaStringOptions.prototype, 'trim', opts); * @api public * @property uppercase * @memberOf SchemaStringOptions - * @type Boolean + * @type {Boolean} * @instance */ @@ -94,7 +94,7 @@ Object.defineProperty(SchemaStringOptions.prototype, 'uppercase', opts); * @api public * @property minLength * @memberOf SchemaStringOptions - * @type Number + * @type {Number} * @instance */ @@ -112,7 +112,7 @@ Object.defineProperty(SchemaStringOptions.prototype, 'minlength', opts); * @api public * @property maxLength * @memberOf SchemaStringOptions - * @type Number + * @type {Number} * @instance */ @@ -125,7 +125,7 @@ Object.defineProperty(SchemaStringOptions.prototype, 'maxlength', opts); * @api public * @property populate * @memberOf SchemaStringOptions - * @type Object + * @type {Object} * @instance */ diff --git a/lib/options/SchemaSubdocumentOptions.js b/lib/options/SchemaSubdocumentOptions.js index e3e624870e5..6782120350a 100644 --- a/lib/options/SchemaSubdocumentOptions.js +++ b/lib/options/SchemaSubdocumentOptions.js @@ -33,7 +33,7 @@ const opts = require('./propertyOptions'); * @api public * @property of * @memberOf SchemaSubdocumentOptions - * @type Function|string + * @type {Function|string} * @instance */ diff --git a/lib/options/SchemaTypeOptions.js b/lib/options/SchemaTypeOptions.js index c9c4a849e53..f2376431034 100644 --- a/lib/options/SchemaTypeOptions.js +++ b/lib/options/SchemaTypeOptions.js @@ -31,7 +31,7 @@ const opts = require('./propertyOptions'); * @api public * @property type * @memberOf SchemaTypeOptions - * @type Function|String|Object + * @type {Function|String|Object} * @instance */ @@ -43,7 +43,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'type', opts); * @api public * @property validate * @memberOf SchemaTypeOptions - * @type Function|Object + * @type {Function|Object} * @instance */ @@ -74,7 +74,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'validate', opts); * @api public * @property cast * @memberOf SchemaTypeOptions - * @type String + * @type {String} * @instance */ @@ -88,7 +88,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'cast', opts); * @api public * @property required * @memberOf SchemaTypeOptions - * @type Function|Boolean + * @type {Function|Boolean} * @instance */ @@ -101,7 +101,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'required', opts); * @api public * @property default * @memberOf SchemaTypeOptions - * @type Function|Any + * @type {Function|Any} * @instance */ @@ -113,7 +113,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'default', opts); * @api public * @property ref * @memberOf SchemaTypeOptions - * @type Function|String + * @type {Function|String} * @instance */ @@ -126,7 +126,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'ref', opts); * @api public * @property ref * @memberOf SchemaTypeOptions - * @type Function|String + * @type {Function|String} * @instance */ @@ -139,7 +139,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'refPath', opts); * @api public * @property select * @memberOf SchemaTypeOptions - * @type Boolean|Number + * @type {Boolean|Number} * @instance */ @@ -152,7 +152,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'select', opts); * @api public * @property index * @memberOf SchemaTypeOptions - * @type Boolean|Number|Object + * @type {Boolean|Number|Object} * @instance */ @@ -166,7 +166,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'index', opts); * @api public * @property unique * @memberOf SchemaTypeOptions - * @type Boolean|Number + * @type {Boolean|Number} * @instance */ @@ -180,7 +180,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'unique', opts); * @api public * @property immutable * @memberOf SchemaTypeOptions - * @type Function|Boolean + * @type {Function|Boolean} * @instance */ @@ -193,7 +193,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'immutable', opts); * @api public * @property sparse * @memberOf SchemaTypeOptions - * @type Boolean|Number + * @type {Boolean|Number} * @instance */ @@ -206,7 +206,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'sparse', opts); * @api public * @property text * @memberOf SchemaTypeOptions - * @type Boolean|Number|Object + * @type {Boolean|Number|Object} * @instance */ @@ -235,7 +235,7 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'text', opts); * @api public * @property transform * @memberOf SchemaTypeOptions - * @type Function + * @type {Function} * @instance */ diff --git a/lib/options/VirtualOptions.js b/lib/options/VirtualOptions.js index 8d00264adfc..3db53b99d27 100644 --- a/lib/options/VirtualOptions.js +++ b/lib/options/VirtualOptions.js @@ -19,7 +19,7 @@ class VirtualOptions { * @api public * @property ref * @memberOf VirtualOptions - * @type String|Model|Function + * @type {String|Model|Function} * @instance */ @@ -32,7 +32,7 @@ Object.defineProperty(VirtualOptions.prototype, 'ref', opts); * @api public * @property refPath * @memberOf VirtualOptions - * @type String|Function + * @type {String|Function} * @instance */ @@ -45,7 +45,7 @@ Object.defineProperty(VirtualOptions.prototype, 'refPath', opts); * @api public * @property localField * @memberOf VirtualOptions - * @type String|Function + * @type {String|Function} * @instance */ @@ -58,7 +58,7 @@ Object.defineProperty(VirtualOptions.prototype, 'localField', opts); * @api public * @property foreignField * @memberOf VirtualOptions - * @type String|Function + * @type {String|Function} * @instance */ @@ -71,7 +71,7 @@ Object.defineProperty(VirtualOptions.prototype, 'foreignField', opts); * @api public * @property justOne * @memberOf VirtualOptions - * @type Boolean + * @type {Boolean} * @instance */ @@ -86,7 +86,7 @@ Object.defineProperty(VirtualOptions.prototype, 'justOne', opts); * @api public * @property count * @memberOf VirtualOptions - * @type Boolean + * @type {Boolean} * @instance */ @@ -99,7 +99,7 @@ Object.defineProperty(VirtualOptions.prototype, 'count', opts); * @api public * @property match * @memberOf VirtualOptions - * @type Object|Function + * @type {Object|Function} * @instance */ @@ -115,7 +115,7 @@ Object.defineProperty(VirtualOptions.prototype, 'match', opts); * @api public * @property options * @memberOf VirtualOptions - * @type Object + * @type {Object} * @instance */ @@ -127,7 +127,7 @@ Object.defineProperty(VirtualOptions.prototype, 'options', opts); * @api public * @property skip * @memberOf VirtualOptions - * @type Number + * @type {Number} * @instance */ @@ -139,7 +139,7 @@ Object.defineProperty(VirtualOptions.prototype, 'skip', opts); * @api public * @property limit * @memberOf VirtualOptions - * @type Number + * @type {Number} * @instance */ @@ -155,7 +155,7 @@ Object.defineProperty(VirtualOptions.prototype, 'limit', opts); * @api public * @property perDocumentLimit * @memberOf VirtualOptions - * @type Number + * @type {Number} * @instance */ diff --git a/lib/schema/boolean.js b/lib/schema/boolean.js index 5eff2c5605d..f09c8dd415e 100644 --- a/lib/schema/boolean.js +++ b/lib/schema/boolean.js @@ -156,7 +156,7 @@ SchemaBoolean.prototype.checkRequired = function(value) { * new M({ b: 'affirmative' }).b; // true * * @property convertToTrue - * @type Set + * @type {Set} * @api public */ @@ -176,7 +176,7 @@ Object.defineProperty(SchemaBoolean, 'convertToTrue', { * new M({ b: 'nay' }).b; // false * * @property convertToFalse - * @type Set + * @type {Set} * @api public */ From 906cb4f724d908fb39a33279cf172ba19bb6458b Mon Sep 17 00:00:00 2001 From: hasezoey Date: Mon, 4 Jul 2022 12:11:29 +0200 Subject: [PATCH 39/43] style: fix missing next line in jsdoc for "Aggregate.prototype.lookup" --- lib/aggregate.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/aggregate.js b/lib/aggregate.js index 9add2c7f3dc..56f80146959 100644 --- a/lib/aggregate.js +++ b/lib/aggregate.js @@ -481,7 +481,8 @@ Aggregate.prototype.sortByCount = function(arg) { * * @see $lookup https://docs.mongodb.org/manual/reference/operator/aggregation/lookup/#pipe._S_lookup * @param {Object} options to $lookup as described in the above link - * @return {Aggregate}* @api public + * @return {Aggregate} + * @api public */ Aggregate.prototype.lookup = function(options) { From e6776b3c397ce1e2eb8e7668e80f069374b02f8b Mon Sep 17 00:00:00 2001 From: hasezoey Date: Mon, 4 Jul 2022 12:32:48 +0200 Subject: [PATCH 40/43] chore(docs/source/api): re-add "null" to types when nullable --- docs/source/api.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/api.js b/docs/source/api.js index a9ee16027ef..021902eac2f 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -179,6 +179,10 @@ function parse() { case 'event': case 'param': ctx[tag.type] = (ctx[tag.type] || []); + // the following is required, because in newer "dox" version "null" is not included in "types" anymore, but a seperate property + if (tag.nullable) { + tag.types.push('null'); + } if (tag.types) { tag.types = tag.types.join('|'); } From a1eade6b26f7b8f57f7727a7681ae6ed09560fce Mon Sep 17 00:00:00 2001 From: hasezoey Date: Mon, 4 Jul 2022 12:51:42 +0200 Subject: [PATCH 41/43] style: update "Query.prototype.box" jsdoc to use proper "@param" tags --- lib/query.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/query.js b/lib/query.js index 9efc3480dd3..a4a185de9dd 100644 --- a/lib/query.js +++ b/lib/query.js @@ -5658,8 +5658,8 @@ if (Symbol.asyncIterator != null) { * @see $box https://docs.mongodb.org/manual/reference/operator/box/ * @see within() Query#within #query_Query-within * @see https://www.mongodb.org/display/DOCS/Geospatial+Indexing - * @param {Object} val - * @param [Array] Upper Right Coords + * @param {Object|Array} val1 Lower Left Coordinates OR a object of lower-left(ll) and upper-right(ur) Coordinates + * @param {Array} [val2] Upper Right Coordinates * @return {Query} this * @api public */ From 4c7e85c1d6a21266030b0a7c5e6855fdf7ba235e Mon Sep 17 00:00:00 2001 From: hasezoey Date: Mon, 4 Jul 2022 13:13:48 +0200 Subject: [PATCH 42/43] chore(docs/source/api): change "return" to overwrite "description" instead of adding to "return" This is changed because "return" property was never used, but the "description" was (in pug files) but i am not familiar with pug to change that Also updates the second "replace" call because "\n" is mostly added to the end which makes it ineffective --- docs/source/api.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index 021902eac2f..2062ac68c1e 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -162,8 +162,8 @@ function parse() { ctx.isFunction = true; break; case 'return': - tag.return = tag.description ? - md.parse(tag.description).replace(/^

/, '').replace(/<\/p>$/, '') : + tag.description = tag.description ? + md.parse(tag.description).replace(/^

/, '').replace(/<\/p>\n?$/, '') : ''; // dox does not add "void" / "undefined" to types, so in the documentation it would result in a empty "«»" From 6a10d4f3d0c39090449c2aa5c00fe09066025e4a Mon Sep 17 00:00:00 2001 From: hasezoey Date: Mon, 4 Jul 2022 13:18:16 +0200 Subject: [PATCH 43/43] style: add ":" to all jsdoc headers where missing This is to change the style to be consistent and headers with ":" seem to be the most used, so it was changed to that --- lib/aggregate.js | 2 +- lib/connection.js | 16 ++--- lib/cursor/AggregationCursor.js | 4 +- lib/cursor/QueryCursor.js | 6 +- lib/document.js | 18 ++--- lib/index.js | 2 +- lib/model.js | 2 +- lib/query.js | 124 ++++++++++++++++---------------- lib/schema.js | 12 ++-- lib/types/decimal128.js | 2 +- lib/types/objectid.js | 2 +- 11 files changed, 95 insertions(+), 95 deletions(-) diff --git a/lib/aggregate.js b/lib/aggregate.js index 56f80146959..7819810107e 100644 --- a/lib/aggregate.js +++ b/lib/aggregate.js @@ -1052,7 +1052,7 @@ Aggregate.prototype.catch = function(reject) { * You do not need to call this function explicitly, the JavaScript runtime * will call it for you. * - * #### Example + * #### Example: * * const agg = Model.aggregate([{ $match: { age: { $gte: 25 } } }]); * for await (const doc of agg) { diff --git a/lib/connection.js b/lib/connection.js index b8a25c92669..61d325a9dd2 100644 --- a/lib/connection.js +++ b/lib/connection.js @@ -93,7 +93,7 @@ Connection.prototype.__proto__ = EventEmitter.prototype; * * Each state change emits its associated event name. * - * #### Example + * #### Example: * * conn.on('connected', callback); * conn.on('disconnected', callback); @@ -193,7 +193,7 @@ Connection.prototype.collections; /** * The name of the database this connection points to. * - * #### Example + * #### Example: * * mongoose.createConnection('mongodb://localhost:27017/mydb').name; // "mydb" * @@ -210,7 +210,7 @@ Connection.prototype.name; * a map from model names to models. Contains all models that have been * added to this connection using [`Connection#model()`](/docs/api/connection.html#connection_Connection-model). * - * #### Example + * #### Example: * * const conn = mongoose.createConnection(); * const Test = conn.model('Test', mongoose.Schema({ name: String })); @@ -230,7 +230,7 @@ Connection.prototype.models; * A number identifier for this connection. Used for debugging when * you have [multiple connections](/docs/connections.html#multiple_connections). * - * #### Example + * #### Example: * * // The default connection has `id = 0` * mongoose.connection.id; // 0 @@ -274,7 +274,7 @@ Object.defineProperty(Connection.prototype, 'plugins', { * The host name portion of the URI. If multiple hosts, such as a replica set, * this will contain the first host name in the URI * - * #### Example + * #### Example: * * mongoose.createConnection('mongodb://localhost:27017/mydb').host; // "localhost" * @@ -294,7 +294,7 @@ Object.defineProperty(Connection.prototype, 'host', { * The port portion of the URI. If multiple hosts, such as a replica set, * this will contain the port from the first host name in the URI. * - * #### Example + * #### Example: * * mongoose.createConnection('mongodb://localhost:27017/mydb').port; // 27017 * @@ -313,7 +313,7 @@ Object.defineProperty(Connection.prototype, 'port', { /** * The username specified in the URI * - * #### Example + * #### Example: * * mongoose.createConnection('mongodb://val:psw@localhost:27017/mydb').user; // "val" * @@ -332,7 +332,7 @@ Object.defineProperty(Connection.prototype, 'user', { /** * The password specified in the URI * - * #### Example + * #### Example: * * mongoose.createConnection('mongodb://val:psw@localhost:27017/mydb').pass; // "psw" * diff --git a/lib/cursor/AggregationCursor.js b/lib/cursor/AggregationCursor.js index 72192757b04..587dbffdee5 100644 --- a/lib/cursor/AggregationCursor.js +++ b/lib/cursor/AggregationCursor.js @@ -107,7 +107,7 @@ if (Symbol.asyncIterator != null) { * Registers a transform function which subsequently maps documents retrieved * via the streams interface or `.next()` * - * #### Example + * #### Example: * * // Map documents returned by `data` events * Thing. @@ -227,7 +227,7 @@ AggregationCursor.prototype.eachAsync = function(fn, opts, callback) { * You do not need to call this function explicitly, the JavaScript runtime * will call it for you. * - * #### Example + * #### Example: * * // Async iterator without explicitly calling `cursor()`. Mongoose still * // creates an AggregationCursor instance internally. diff --git a/lib/cursor/QueryCursor.js b/lib/cursor/QueryCursor.js index 663973405ac..baa7710b107 100644 --- a/lib/cursor/QueryCursor.js +++ b/lib/cursor/QueryCursor.js @@ -112,7 +112,7 @@ QueryCursor.prototype._read = function() { * Registers a transform function which subsequently maps documents retrieved * via the streams interface or `.next()` * - * #### Example + * #### Example: * * // Map documents returned by `data` events * Thing. @@ -212,7 +212,7 @@ QueryCursor.prototype.next = function(callback) { * will wait for the promise to resolve before iterating on to the next one. * Returns a promise that resolves when done. * - * #### Example + * #### Example: * * // Iterate over documents asynchronously * Thing. @@ -301,7 +301,7 @@ QueryCursor.prototype._transformForAsyncIterator = function() { * You do not need to call this function explicitly, the JavaScript runtime * will call it for you. * - * #### Example + * #### Example: * * // Works without using `cursor()` * for await (const doc of Model.find([{ $sort: { name: 1 } }])) { diff --git a/lib/document.js b/lib/document.js index bef20b9f560..6b3c9622a82 100644 --- a/lib/document.js +++ b/lib/document.js @@ -1718,7 +1718,7 @@ Document.prototype.$__setValue = function(path, val) { /** * Returns the value of a path. * - * #### Example + * #### Example: * * // path * doc.get('age') // 47 @@ -1891,7 +1891,7 @@ Document.prototype.$ignore = function(path) { * A path `a` may be in `modifiedPaths()` but not in `directModifiedPaths()` * because a child of `a` was directly modified. * - * #### Example + * #### Example: * const schema = new Schema({ foo: String, nested: { bar: String } }); * const Model = mongoose.model('Test', schema); * await Model.create({ foo: 'original', nested: { bar: 'original' } }); @@ -2047,7 +2047,7 @@ Document.prototype[documentModifiedPaths] = Document.prototype.modifiedPaths; * * If `path` is given, checks if a path or any full path containing `path` as part of its path chain has been modified. * - * #### Example + * #### Example: * * doc.set('documents.0.title', 'changed'); * doc.isModified() // true @@ -2093,7 +2093,7 @@ Document.prototype[documentIsModified] = Document.prototype.isModified; /** * Checks if a path is set to its default. * - * #### Example + * #### Example: * * MyModel = mongoose.model('test', { name: { type: String, default: 'Val '} }); * const m = new MyModel(); @@ -2157,7 +2157,7 @@ Document.prototype.$isDeleted = function(val) { /** * Returns true if `path` was directly set and modified, else false. * - * #### Example + * #### Example: * * doc.set('documents.0.title', 'changed'); * doc.isDirectModified('documents.0.title') // true @@ -2213,7 +2213,7 @@ Document.prototype.isInit = function(path) { /** * Checks if `path` was selected in the source query which initialized this document. * - * #### Example + * #### Example: * * const doc = await Thing.findOne().select('name'); * doc.isSelected('name') // true @@ -2294,7 +2294,7 @@ Document.prototype.$__isSelected = Document.prototype.isSelected; * Checks if `path` was explicitly selected. If no projection, always returns * true. * - * #### Example + * #### Example: * * Thing.findOne().select('nested.name').exec(function (err, doc) { * doc.isDirectSelected('nested.name') // true @@ -3636,7 +3636,7 @@ Document.prototype.$toObject = function(options, json) { * * schema.set('toObject', { virtuals: true }) * - * #### Transform + * #### Transform: * * We may need to perform a transformation of the resulting object based on some criteria, say to remove some sensitive information or return a custom object. In this case we set the optional `transform` function. * @@ -3648,7 +3648,7 @@ Document.prototype.$toObject = function(options, json) { * - `ret` The plain object representation which has been converted * - `options` The options in use (either schema options or the options passed inline) * - * #### Example + * #### Example: * * // specify the transform schema option * if (!schema.options.toObject) schema.options.toObject = {}; diff --git a/lib/index.js b/lib/index.js index 89c5101f032..570f6dca46d 100644 --- a/lib/index.js +++ b/lib/index.js @@ -801,7 +801,7 @@ Object.defineProperty(Mongoose.prototype, 'Connection', { /** * The Mongoose version * - * #### Example + * #### Example: * * console.log(mongoose.version); // '5.x.x' * diff --git a/lib/model.js b/lib/model.js index 4b69dea9554..8904c43cbf2 100644 --- a/lib/model.js +++ b/lib/model.js @@ -2384,7 +2384,7 @@ Model.count = function count(conditions, callback) { * * Passing a `callback` executes the query. * - * #### Example + * #### Example: * * Link.distinct('url', { clicks: {$gt: 100}}, function (err, result) { * if (err) return handleError(err); diff --git a/lib/query.js b/lib/query.js index a4a185de9dd..e82986c8932 100644 --- a/lib/query.js +++ b/lib/query.js @@ -179,7 +179,7 @@ Query.use$geoWithin = mquery.use$geoWithin; /** * Converts this query to a customized, reusable query constructor with all arguments and options retained. * - * #### Example + * #### Example: * * // Create a query for adventure movies and read from the primary * // node in the replica-set unless it is down, in which case we'll @@ -309,7 +309,7 @@ Query.prototype.clone = function clone() { /** * Specifies a javascript function or expression to pass to MongoDBs query system. * - * #### Example + * #### Example: * * query.$where('this.comments.length === 10 || this.name.length === 5') * @@ -337,7 +337,7 @@ Query.prototype.clone = function clone() { /** * Specifies a `path` for use with chaining. * - * #### Example + * #### Example: * * // instead of writing: * User.find({age: {$gte: 21, $lte: 65}}, callback); @@ -367,7 +367,7 @@ Query.prototype.clone = function clone() { /** * Specifies a `$slice` projection for an array. * - * #### Example + * #### Example: * * query.slice('comments', 5); * query.slice('comments', -5); @@ -445,7 +445,7 @@ Query.prototype._validateOp = function() { /** * Specifies the complementary comparison value for paths specified with `where()` * - * #### Example + * #### Example: * * User.where('age').equals(49); * @@ -464,7 +464,7 @@ Query.prototype._validateOp = function() { /** * Specifies arguments for an `$or` condition. * - * #### Example + * #### Example: * * query.or([{ color: 'red' }, { status: 'emergency' }]); * @@ -480,7 +480,7 @@ Query.prototype._validateOp = function() { /** * Specifies arguments for a `$nor` condition. * - * #### Example + * #### Example: * * query.nor([{ color: 'green' }, { status: 'ok' }]); * @@ -496,7 +496,7 @@ Query.prototype._validateOp = function() { /** * Specifies arguments for a `$and` condition. * - * #### Example + * #### Example: * * query.and([{ color: 'green' }, { status: 'ok' }]) * @@ -514,7 +514,7 @@ Query.prototype._validateOp = function() { * * When called with one argument, the most recent path passed to `where()` is used. * - * #### Example + * #### Example: * * Thing.find().where('age').gt(21); * @@ -639,7 +639,7 @@ Query.prototype._validateOp = function() { * * When called with one argument, the most recent path passed to `where()` is used. * - * #### Example + * #### Example: * * const docs = await MyModel.where('tags').size(0).exec(); * assert(Array.isArray(docs)); @@ -686,7 +686,7 @@ Query.prototype._validateOp = function() { * Specifies a `$mod` condition, filters documents for documents whose * `path` property is a number that is equal to `remainder` modulo `divisor`. * - * #### Example + * #### Example: * * // All find products whose inventory is odd * Product.find().mod('inventory', [2, 1]); @@ -732,7 +732,7 @@ Query.prototype.mod = function() { /** * Specifies an `$exists` condition * - * #### Example + * #### Example: * * // { name: { $exists: true }} * Thing.where('name').exists() @@ -756,7 +756,7 @@ Query.prototype.mod = function() { /** * Specifies an `$elemMatch` condition * - * #### Example + * #### Example: * * query.elemMatch('comment', { author: 'autobot', votes: {$gte: 5}}) * @@ -785,7 +785,7 @@ Query.prototype.mod = function() { /** * Defines a `$within` or `$geoWithin` argument for geo-spatial queries. * - * #### Example + * #### Example: * * query.where(path).within().box() * query.where(path).within().circle() @@ -824,11 +824,11 @@ Query.prototype.mod = function() { /** * Specifies the maximum number of documents the query will return. * - * #### Example + * #### Example: * * query.limit(20); * - * #### Note + * #### Note: * * Cannot be used with `distinct()` * @@ -857,11 +857,11 @@ Query.prototype.limit = function limit(v) { /** * Specifies the number of documents to skip. * - * #### Example + * #### Example: * * query.skip(100).limit(20); * - * #### Note + * #### Note: * * Cannot be used with `distinct()` * @@ -891,11 +891,11 @@ Query.prototype.skip = function skip(v) { /** * Specifies the maxScan option. * - * #### Example + * #### Example: * * query.maxScan(100); * - * #### Note + * #### Note: * * Cannot be used with `distinct()` * @@ -910,11 +910,11 @@ Query.prototype.skip = function skip(v) { /** * Specifies the batchSize option. * - * #### Example + * #### Example: * * query.batchSize(100) * - * #### Note + * #### Note: * * Cannot be used with `distinct()` * @@ -929,11 +929,11 @@ Query.prototype.skip = function skip(v) { /** * Specifies the `comment` option. * - * #### Example + * #### Example: * * query.comment('login query') * - * #### Note + * #### Note: * * Cannot be used with `distinct()` * @@ -948,13 +948,13 @@ Query.prototype.skip = function skip(v) { /** * Specifies this query as a `snapshot` query. * - * #### Example + * #### Example: * * query.snapshot(); // true * query.snapshot(true); * query.snapshot(false); * - * #### Note + * #### Note: * * Cannot be used with `distinct()` * @@ -969,11 +969,11 @@ Query.prototype.skip = function skip(v) { /** * Sets query hints. * - * #### Example + * #### Example: * * query.hint({ indexA: 1, indexB: -1 }); * - * #### Note + * #### Note: * * Cannot be used with `distinct()` * @@ -1036,7 +1036,7 @@ Query.prototype.projection = function(arg) { * either list the fields to include (which excludes all others), or list the fields * to exclude (which implies all other fields are included). The [`_id` field is the only exception because MongoDB includes it by default](https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/#suppress-id-field). * - * #### Example + * #### Example: * * // include a and b, exclude other fields * query.select('a b'); @@ -2291,7 +2291,7 @@ Query.prototype._find = wrapThunk(function(callback) { * If there are too many documents in the result to fit in memory, use * [`Query.prototype.cursor()`](api.html#query_Query-cursor) * - * #### Example + * #### Example: * * // Using async/await * const arr = await Movie.find({ year: { $gte: 1980, $lte: 1989 } }); @@ -2506,7 +2506,7 @@ Query.prototype._findOne = wrapThunk(function(callback) { * * - `findOne()` * - * #### Example + * #### Example: * * const query = Kitten.where({ color: 'white' }); * query.findOne(function (err, kitten) { @@ -2857,7 +2857,7 @@ Query.prototype.__distinct = wrapThunk(function __distinct(callback) { * * This function does not trigger any middleware. * - * #### Example + * #### Example: * * distinct(field, conditions, callback) * distinct(field, conditions) @@ -2918,7 +2918,7 @@ Query.prototype.distinct = function(field, conditions, callback) { * sort order of each path is ascending unless the path name is prefixed with `-` * which will be treated as descending. * - * #### Example + * #### Example: * * // sort by "field" ascending and "test" descending * query.sort({ field: 'asc', test: -1 }); @@ -2926,7 +2926,7 @@ Query.prototype.distinct = function(field, conditions, callback) { * // equivalent * query.sort('field -test'); * - * #### Note + * #### Note: * * Cannot be used with `distinct()` * @@ -2951,7 +2951,7 @@ Query.prototype.sort = function(arg) { * * This function does not trigger any middleware * - * #### Example + * #### Example: * * Character.remove({ name: /Stark/ }, callback); * @@ -2963,13 +2963,13 @@ Query.prototype.sort = function(arg) { * - `deletedCount`: the number of documents deleted * - `n`: the number of documents deleted. Equal to `deletedCount`. * - * #### Example + * #### Example: * * const res = await Character.remove({ name: /Stark/ }); * // Number of docs deleted * res.deletedCount; * - * #### Note + * #### Note: * * Calling `remove()` creates a [Mongoose query](./queries.html), and a query * does not execute until you either pass a callback, call [`Query#then()`](#query_Query-then), @@ -3043,7 +3043,7 @@ Query.prototype._remove = wrapThunk(function(callback) { * * This function triggers `deleteOne` middleware. * - * #### Example + * #### Example: * * await Character.deleteOne({ name: 'Eddard Stark' }); * @@ -3058,7 +3058,7 @@ Query.prototype._remove = wrapThunk(function(callback) { * - `deletedCount`: the number of documents deleted * - `n`: the number of documents deleted. Equal to `deletedCount`. * - * #### Example + * #### Example: * * const res = await Character.deleteOne({ name: 'Eddard Stark' }); * // `1` if MongoDB deleted a doc, `0` if no docs matched the filter `{ name: ... }` @@ -3129,7 +3129,7 @@ Query.prototype._deleteOne = wrapThunk(function(callback) { * * This function triggers `deleteMany` middleware. * - * #### Example + * #### Example: * * await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }); * @@ -3144,7 +3144,7 @@ Query.prototype._deleteOne = wrapThunk(function(callback) { * - `deletedCount`: the number of documents deleted * - `n`: the number of documents deleted. Equal to `deletedCount`. * - * #### Example + * #### Example: * * const res = await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }); * // `0` if no docs matched the filter, number of docs deleted otherwise @@ -3296,7 +3296,7 @@ function prepareDiscriminatorCriteria(query) { * // doc: the document before updates are applied if `new: false`, or after updates if `new = true` * } * - * #### Examples + * #### Examples: * * query.findOneAndUpdate(conditions, update, options, callback) // executes * query.findOneAndUpdate(conditions, update, options) // returns Query @@ -3438,7 +3438,7 @@ Query.prototype._findOneAndUpdate = wrapThunk(function(callback) { * // doc: the document before updates are applied if `new: false`, or after updates if `new = true` * } * - * #### Examples + * #### Examples: * * A.where().findOneAndRemove(conditions, options, callback) // executes * A.where().findOneAndRemove(conditions, options) // return Query @@ -3525,7 +3525,7 @@ Query.prototype.findOneAndRemove = function(conditions, options, callback) { * // doc: the document before updates are applied if `new: false`, or after updates if `new = true` * } * - * #### Examples + * #### Examples: * * A.where().findOneAndDelete(conditions, options, callback) // executes * A.where().findOneAndDelete(conditions, options) // return Query @@ -3644,7 +3644,7 @@ Query.prototype._findOneAndDelete = wrapThunk(function(callback) { * // doc: the document before updates are applied if `new: false`, or after updates if `new = true` * } * - * #### Examples + * #### Examples: * * A.where().findOneAndReplace(filter, replacement, options, callback); // executes * A.where().findOneAndReplace(filter, replacement, options); // return Query @@ -4285,7 +4285,7 @@ Query.prototype._replaceOne = wrapThunk(function(callback) { * * - `update()` * - * #### Example + * #### Example: * * Model.where({ _id: id }).update({ title: 'words' }); * @@ -4303,11 +4303,11 @@ Query.prototype._replaceOne = wrapThunk(function(callback) { * - `read` * - `writeConcern` * - * #### Note + * #### Note: * * Passing an empty object `{}` as the doc will result in a no-op. The update operation will be ignored and the callback executed without sending the command to MongoDB. * - * #### Note + * #### Note: * * The operation is only executed when a callback is passed. To force execution without a callback, we must first call update() and then execute it by using the `exec()` method. * @@ -5164,7 +5164,7 @@ function _getPopulatedPaths(list, arr, prefix) { /** * Casts this query to the schema of `model` * - * #### Note + * #### Note: * * If `obj` is present, it is cast instead of this query. * @@ -5289,7 +5289,7 @@ Query.prototype._applyPaths = function applyPaths() { * * The `.cursor()` function triggers pre find hooks, but **not** post find hooks. * - * #### Example + * #### Example: * * // There are 2 ways to use a cursor. First, as a stream: * Thing. @@ -5360,7 +5360,7 @@ Query.prototype.maxscan = Query.base.maxScan; /** * Sets the tailable option (for use with capped collections). * - * #### Example + * #### Example: * * query.tailable(); // true * query.tailable(true); @@ -5369,7 +5369,7 @@ Query.prototype.maxscan = Query.base.maxScan; * // Set both `tailable` and `awaitData` options * query.tailable({ awaitData: true }); * - * #### Note + * #### Note: * * Cannot be used with `distinct()` * @@ -5410,7 +5410,7 @@ Query.prototype.tailable = function(val, opts) { /** * Declares an intersects query for `geometry()`. * - * #### Example + * #### Example: * * query.where('path').intersects().geometry({ * type: 'LineString', @@ -5443,7 +5443,7 @@ Query.prototype.tailable = function(val, opts) { /** * Specifies a `$geometry` condition * - * #### Example + * #### Example: * * const polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]] * query.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA }) @@ -5485,7 +5485,7 @@ Query.prototype.tailable = function(val, opts) { * * These operators return documents sorted by distance. * - * #### Example + * #### Example: * * query.where('loc').near({ center: [10, 10] }); * query.where('loc').near({ center: [10, 10], maxDistance: 5 }); @@ -5568,13 +5568,13 @@ Query.prototype.near = function() { /** * _DEPRECATED_ Specifies a `$nearSphere` condition * - * #### Example + * #### Example: * * query.where('loc').nearSphere({ center: [10, 10], maxDistance: 5 }); * * **Deprecated.** Use `query.near()` instead with the `spherical` option set to `true`. * - * #### Example + * #### Example: * * query.where('loc').near({ center: [10, 10], spherical: true }); * @@ -5597,7 +5597,7 @@ Query.prototype.nearSphere = function() { * You do not need to call this function explicitly, the JavaScript runtime * will call it for you. * - * #### Example + * #### Example: * * for await (const doc of Model.aggregate([{ $sort: { name: 1 } }])) { * console.log(doc.name); @@ -5625,7 +5625,7 @@ if (Symbol.asyncIterator != null) { /** * Specifies a `$polygon` condition * - * #### Example + * #### Example: * * query.where('loc').within().polygon([10, 20], [13, 25], [7, 15]); * query.polygon('loc', [10, 20], [13, 25], [7, 15]); @@ -5644,7 +5644,7 @@ if (Symbol.asyncIterator != null) { /** * Specifies a `$box` condition * - * #### Example + * #### Example: * * const lowerLeft = [40.73083, -73.99756] * const upperRight= [40.741404, -73.988135] @@ -5681,7 +5681,7 @@ Query.prototype.box = function(ll, ur) { /** * Specifies a `$center` or `$centerSphere` condition. * - * #### Example + * #### Example: * * const area = { center: [50, 50], radius: 10, unique: true } * query.where('loc').within().circle(area) @@ -5726,7 +5726,7 @@ Query.prototype.center = Query.base.circle; * * **Deprecated.** Use [circle](#query_Query-circle) instead. * - * #### Example + * #### Example: * * const area = { center: [50, 50], radius: 10 }; * query.where('loc').within().centerSphere(area); diff --git a/lib/schema.js b/lib/schema.js index 83ea482cd30..26144de75a5 100644 --- a/lib/schema.js +++ b/lib/schema.js @@ -788,7 +788,7 @@ reserved.collection = 1; * Sets a path (if arity 2) * Gets a path (if arity 1) * - * #### Example + * #### Example: * * schema.path('name') // returns a SchemaType * schema.path('name', Number) // changes the schemaType of `name` to Number @@ -1545,7 +1545,7 @@ Schema.prototype.queue = function(name, args) { /** * Defines a pre hook for the model. * - * #### Example + * #### Example: * * const toySchema = new Schema({ name: String, created: Date }); * @@ -1701,7 +1701,7 @@ Schema.prototype.plugin = function(fn, opts) { /** * Adds an instance method to documents constructed from Models compiled from this schema. * - * #### Example + * #### Example: * * const schema = kittySchema = new Schema(..); * @@ -1748,7 +1748,7 @@ Schema.prototype.method = function(name, fn, options) { /** * Adds static "class" methods to Models compiled from this schema. * - * #### Example + * #### Example: * * const schema = new Schema(..); * // Equivalent to `schema.statics.findByName = function(name) {}`; @@ -1781,7 +1781,7 @@ Schema.prototype.static = function(name, fn) { /** * Defines an index (most likely compound) for this schema. * - * #### Example + * #### Example: * * schema.index({ first: 1, last: -1 }) * @@ -1806,7 +1806,7 @@ Schema.prototype.index = function(fields, options) { /** * Sets a schema option. * - * #### Example + * #### Example: * * schema.set('strict'); // 'true' by default * schema.set('strict', false); // Sets 'strict' to false diff --git a/lib/types/decimal128.js b/lib/types/decimal128.js index b4459329ad9..15173385b72 100644 --- a/lib/types/decimal128.js +++ b/lib/types/decimal128.js @@ -1,7 +1,7 @@ /** * Decimal128 type constructor * - * #### Example + * #### Example: * * const id = new mongoose.Types.Decimal128('3.1415'); * diff --git a/lib/types/objectid.js b/lib/types/objectid.js index fa08503fe80..ab73119cb55 100644 --- a/lib/types/objectid.js +++ b/lib/types/objectid.js @@ -1,7 +1,7 @@ /** * ObjectId type constructor * - * #### Example + * #### Example: * * const id = new mongoose.Types.ObjectId; *