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

@@ -50,13 +50,35 @@ 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();
 
+/**
+ * @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
+ * @property {string} [deprecated] Defines wheter the current Property is signaled as deprecated
+ */
+
 function parse() {
   for (const props of combinedFiles) {
     let name = props.file.
@@ -88,43 +110,67 @@ function parse() {
       if (prop.ignore || prop.isPrivate) {
         continue;
       }
-
+
+      /** @type {PropContext} */
       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':
             ctx.constructor = tag.string;
             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);
               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;
             break;
           case 'static':
             ctx.type = 'property';
-            ctx.static = true;
-            ctx.name = tag.string;
-            ctx.string = `${data.name}.${ctx.name}`;
+            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;
             break;
           case 'function':
             ctx.type = 'function';
-            ctx.static = true;
+            ctx.isStatic = true;
             ctx.name = tag.string;
-            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 ?
               md.parse(tag.description).replace(/^<p>/, '').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':
@@ -147,26 +193,49 @@ 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.string += '()';
-            }
             break;
           case 'constructor':
-            ctx.string = tag.string + '()';
+            ctx.string = tag.string;
             ctx.name = tag.string;
+            ctx.isFunction = true;
+            break;
+          case 'instance':
+            ctx.isInstance = true;
+            break;
+          case 'deprecated':
+            ctx.deprecated = true;
+            break;
         }
       }
 
+      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}")`);
+      }
+
+      // 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}`;
+      }
+
+      // 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') {
@@ -178,9 +247,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} 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 = {};

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