Update dox to latest version and fix some documentation issues

.gitignore

@@ -48,4 +48,7 @@ docs/*.html
 docs/tutorials/*.html
 docs/typescript/*.html
 docs/api/*.html
-index.html
+index.html
+
+# yarn package-lock
+yarn.lock

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();
@@ -94,7 +100,10 @@ function parse() {
             break;
           case 'property':
             ctx.type = 'property';
+
+            // 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) {
               ctx.type = match[0].substring(1, match[0].length - 1);
@@ -109,14 +118,18 @@ function parse() {
           case 'static':
             ctx.type = 'property';
             ctx.static = true;
-            ctx.name = tag.string;
-            ctx.string = `${data.name}.${ctx.name}`;
+            // 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.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;
             break;
           case 'return':
             tag.return = tag.description ?
@@ -144,21 +157,27 @@ 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;
         }
       }
 
+      if (ctx.isFunction && !ctx.string.endsWith("()")) {
+        ctx.string = ctx.string + "()";
+      }
+
       if (/\.prototype[^.]/.test(ctx.string)) {
         ctx.string = `${ctx.constructor}.prototype.${ctx.name}`;
       }
@@ -175,9 +194,6 @@ function parse() {
       ctx.description = prop.description.full.
         replace(/<br \/>/ig, ' ').
         replace(/&gt;/ig, '>');
-      if (ctx.description.includes('function capitalize')) {
-        console.log('\n\n-------\n\n', ctx);
-      }
       ctx.description = md.parse(ctx.description);
 
       data.props.push(ctx);

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 = {};

lib/cursor/AggregationCursor.js

@@ -132,6 +132,7 @@ if (Symbol.asyncIterator != null) {
  *
  * @param {Function} fn
  * @return {AggregationCursor}
+ * @memberOf AggregationCursor
  * @api public
  * @method map
  */

lib/cursor/QueryCursor.js

@@ -137,6 +137,7 @@ QueryCursor.prototype._read = function() {
  *
  * @param {Function} fn
  * @return {QueryCursor}
+ * @memberOf QueryCursor
  * @api public
  * @method map
  */
@@ -320,7 +321,7 @@ QueryCursor.prototype._transformForAsyncIterator = function() {
  * support async iterators.
  *
  * @method Symbol.asyncIterator
- * @memberOf Query
+ * @memberOf QueryCursor
  * @instance
  * @api public
  */

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');

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
  */

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

lib/index.js

@@ -761,6 +761,8 @@ Mongoose.prototype.Aggregate = Aggregate;
 /**
  * The Mongoose Collection constructor
  *
+ * @memberOf Mongoose
+ * @instance
  * @method Collection
  * @api public
  */
@@ -1044,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.
- * @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;

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;
@@ -899,6 +899,7 @@ Model.prototype.$__version = function(where, delta) {
  *     })
  *
  * @see versionKeys https://mongoosejs.com/docs/guide.html#versionKey
+ * @memberOf Model
  * @api public
  */
 
@@ -1453,7 +1454,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
  */
 
@@ -3613,7 +3614,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<Document>} 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,10 +3688,10 @@ function handleSuccessfulWrite(document, resolve, reject) {
 
 /**
  *
- * @param {[Document]} documents The array of documents to build write operations of
+ * @param {Array<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<Promise>} Returns a array of all Promises the function executes to be awaited.
  */
 Model.buildBulkWriteOperations = function buildBulkWriteOperations(documents, options) {
   if (!Array.isArray(documents)) {

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
  */

lib/schema.js

@@ -1874,7 +1874,7 @@ Schema.prototype.get = function(key) {
  * The allowed index types
  *
  * @receiver Schema
- * @static indexTypes
+ * @static
  * @api public
  */
 

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 {*} value - value for option
- * @return {undefined}
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
+ * @return {void}
  * @function set
  * @static
  * @api public
  */
 
-SubdocumentPath.defaultOptions = {};
-
 SubdocumentPath.set = SchemaType.set;
 
 /*!