Merge pull request #12337 from hasezoey/changeCommentType

Change Comments from `/*!` to `/**` to make possible jsdoc available

examples/redis-todo/routers/todoRouter.js

@@ -5,7 +5,7 @@ const Todo = require('../db/models/todoModel');
 const auth = require('../middleware/auth');
 const clearCache = require('../middleware/clearCache');
 
-/* @private
+/* @api private
  * @func: fetch all user todos
  * @input: user id
  * @return: todos
@@ -19,7 +19,7 @@ Router.get('/all', auth, async function({ userId }, res) {
   }
 });
 
-/* @private
+/* @api private
  * @func: create todo
  * @input: todo data, userid
  * @return: todo
@@ -38,7 +38,7 @@ Router.post('/create', auth, clearCache, async function({ userId, body }, res) {
   }
 });
 
-/* @private
+/* @api private
  * @func: update todo
  * @input: todo data, todoId, userid
  * @return: updated todo
@@ -57,7 +57,7 @@ Router.post('/update', auth, async function({ userId, body }, res) {
   }
 });
 
-/* @private
+/* @api private
  * @func: delete todo
  * @input: todoId, userid
  */

examples/redis-todo/routers/userRouter.js

@@ -57,7 +57,7 @@ Router.post('/login', async function({ body }, res) {
   }
 });
 
-/* @private
+/* @api private
  * @func: edit user
  * @input: username, name or password
  * @return: edited user
@@ -82,7 +82,7 @@ Router.post('/update', auth, async function({ userId, body }, res) {
   }
 });
 
-/* @private
+/* @api private
  * @func: delete user
  */
 Router.delete('/delete', auth, async function({ userId }, res) {

lib/aggregate.js

@@ -1104,12 +1104,13 @@ function isOperator(obj) {
   return k.length === 1 && k[0][0] === '$';
 }
 
-/*!
+/**
  * Adds the appropriate `$match` pipeline step to the top of an aggregate's
  * pipeline, should it's model is a non-root discriminator type. This is
  * analogous to the `prepareDiscriminatorCriteria` function in `lib/query.js`.
  *
  * @param {Aggregate} aggregate Aggregate to prepare
+ * @api private
  */
 
 Aggregate._prepareDiscriminatorPipeline = prepareDiscriminatorPipeline;

lib/cast/boolean.js

@@ -2,7 +2,7 @@
 
 const CastError = require('../error/cast');
 
-/*!
+/**
  * Given a value, cast it to a boolean, or throw a `CastError` if the value
  * cannot be casted. `null` and `undefined` are considered valid.
  *

lib/cast/number.js

@@ -2,7 +2,7 @@
 
 const assert = require('assert');
 
-/*!
+/**
  * Given a value, cast it to a number, or throw an `Error` if the value
  * cannot be casted. `null` and `undefined` are considered valid.
  *

lib/cast/string.js

@@ -2,7 +2,7 @@
 
 const CastError = require('../error/cast');
 
-/*!
+/**
  * Given a value, cast it to a string, or throw a `CastError` if the value
  * cannot be casted. `null` and `undefined` are considered valid.
  *

lib/connection.js

@@ -26,7 +26,7 @@ const processConnectionOptions = require('./helpers/processConnectionOptions');
 const arrayAtomicsSymbol = require('./helpers/symbols').arrayAtomicsSymbol;
 const sessionNewDocuments = require('./helpers/symbols').sessionNewDocuments;
 
-/*!
+/**
  * A list of authentication mechanisms that don't require a password for authentication.
  * This is used by the authMechanismDoesNotRequirePassword method.
  *

lib/cursor/AggregationCursor.js

@@ -71,8 +71,12 @@ function _init(model, c, agg) {
   }
 }
 
-/*!
+/**
  * Necessary to satisfy the Readable API
+ * @method _read
+ * @memberOf AggregationCursor
+ * @instance
+ * @api private
  */
 
 AggregationCursor.prototype._read = function() {
@@ -147,8 +151,12 @@ Object.defineProperty(AggregationCursor.prototype, 'map', {
   writable: true
 });
 
-/*!
+/**
  * Marks this cursor as errored
+ * @method _markError
+ * @instance
+ * @memberOf AggregationCursor
+ * @api private
  */
 
 AggregationCursor.prototype._markError = function(error) {
@@ -324,9 +332,12 @@ function _waitForCursor(ctx, cb) {
   });
 }
 
-/*!
+/**
  * Get the next doc from the underlying cursor and mongooseify it
  * (populate, etc.)
+ * @param {Any} ctx
+ * @param {Function} cb
+ * @api private
  */
 
 function _next(ctx, cb) {

lib/cursor/QueryCursor.js

@@ -85,8 +85,12 @@ function QueryCursor(query, options) {
 
 util.inherits(QueryCursor, Readable);
 
-/*!
+/**
  * Necessary to satisfy the Readable API
+ * @method _read
+ * @memberOf QueryCursor
+ * @instance
+ * @api private
  */
 
 QueryCursor.prototype._read = function() {
@@ -152,8 +156,12 @@ Object.defineProperty(QueryCursor.prototype, 'map', {
   writable: true
 });
 
-/*!
+/**
  * Marks this cursor as errored
+ * @method _markError
+ * @memberOf QueryCursor
+ * @instance
+ * @api private
  */
 
 QueryCursor.prototype._markError = function(error) {
@@ -340,9 +348,12 @@ function _transformForAsyncIterator(doc) {
   return doc == null ? { done: true } : { value: doc, done: false };
 }
 
-/*!
+/**
  * Get the next doc from the underlying cursor and mongooseify it
  * (populate, etc.)
+ * @param {Any} ctx
+ * @param {Function} cb
+ * @api private
  */
 
 function _next(ctx, cb) {

lib/document.js

@@ -696,12 +696,15 @@ Document.prototype.$__init = function(doc, opts) {
   return this;
 };
 
-/*!
+/**
  * Init helper.
  *
  * @param {Object} self document instance
  * @param {Object} obj raw mongodb doc
  * @param {Object} doc object we are initializing
+ * @param {Object} [opts] Optional Options
+ * @param {Boolean} [opts.setters] Call `applySetters` instead of `cast`
+ * @param {String} [prefix] Prefix to add to each path
  * @api private
  */
 
@@ -3815,11 +3818,12 @@ Document.prototype.toObject = function(options) {
   return this.$toObject(options);
 };
 
-/*!
+/**
  * Minimizes an object, removing undefined values and empty objects
  *
  * @param {Object} object to minimize
  * @return {Object}
+ * @api private
  */
 
 function minimize(obj) {
@@ -3925,12 +3929,14 @@ function applyVirtuals(self, json, options, toObjectOptions) {
 }
 
 
-/*!
+/**
  * Applies virtuals properties to `json`.
  *
  * @param {Document} self
  * @param {Object} json
+ * @param {Object} [options]
  * @return {Object} `json`
+ * @api private
  */
 
 function applyGetters(self, json, options) {
@@ -3980,12 +3986,13 @@ function applyGetters(self, json, options) {
   return json;
 }
 
-/*!
+/**
  * Applies schema type transforms to `json`.
  *
  * @param {Document} self
  * @param {Object} json
  * @return {Object} `json`
+ * @api private
  */
 
 function applySchemaTypeTransforms(self, json) {
@@ -4158,10 +4165,7 @@ Document.prototype.inspect = function(options) {
 };
 
 if (inspect.custom) {
-  /*!
-  * Avoid Node deprecation warning DEP0079
-  */
-
+  // Avoid Node deprecation warning DEP0079
   Document.prototype[inspect.custom] = Document.prototype.inspect;
 }
 

lib/drivers/browser/objectid.js

@@ -9,8 +9,9 @@
 
 const ObjectId = require('bson').ObjectID;
 
-/*!
+/**
  * Getter for convenience with populate, see gh-6115
+ * @api private
  */
 
 Object.defineProperty(ObjectId.prototype, '_id', {

lib/drivers/node-mongodb-native/ReadPreference.js

@@ -7,7 +7,7 @@
 const mongodb = require('mongodb');
 const ReadPref = mongodb.ReadPreference;
 
-/*!
+/**
  * Converts arguments to ReadPrefs the driver
  * can understand.
  *

lib/drivers/node-mongodb-native/collection.js

@@ -66,8 +66,10 @@ NativeCollection.prototype.onClose = function(force) {
 
 const syncCollectionMethods = { watch: true, find: true, aggregate: true };
 
-/*!
+/**
  * Copy the collection methods and make them subject to queues
+ * @param {Number|String} I
+ * @api private
  */
 
 function iter(i) {
@@ -296,8 +298,10 @@ NativeCollection.prototype.$format = function(arg, color, shell) {
   return format(arg, false, color, shell);
 };
 
-/*!
+/**
  * Debug print helper
+ * @param {Any} representation
+ * @api private
  */
 
 function inspectable(representation) {

lib/error/browserMissingSchema.js

@@ -8,7 +8,7 @@ const MongooseError = require('./');
 
 
 class MissingSchemaError extends MongooseError {
-  /*!
+  /**
    * MissingSchema Error constructor.
    */
   constructor() {

lib/error/cast.js

@@ -56,9 +56,10 @@ class CastError extends MongooseError {
     this.valueType = getValueType(value);
   }
 
-  /*!
+  /**
    * ignore
    * @param {Readonly<CastError>} other
+   * @api private
    */
   copy(other) {
     this.messageFormat = other.messageFormat;

lib/error/divergentArray.js

@@ -8,9 +8,10 @@
 const MongooseError = require('./');
 
 class DivergentArrayError extends MongooseError {
-  /*!
+  /**
    * DivergentArrayError constructor.
    * @param {Array<String>} paths
+   * @api private
    */
   constructor(paths) {
     const msg = 'For your own good, using `document.save()` to update an array '

lib/error/missingSchema.js

@@ -8,9 +8,10 @@
 const MongooseError = require('./');
 
 class MissingSchemaError extends MongooseError {
-  /*!
+  /**
    * MissingSchema Error constructor.
    * @param {String} name
+   * @api private
    */
   constructor(name) {
     const msg = 'Schema hasn\'t been registered for model "' + name + '".\n'

lib/error/notFound.js

@@ -8,8 +8,9 @@ const MongooseError = require('./');
 const util = require('util');
 
 class DocumentNotFoundError extends MongooseError {
-  /*!
+  /**
    * OverwriteModel Error constructor.
+   * @api private
    */
   constructor(filter, model, numAffected, result) {
     let msg;

lib/error/overwriteModel.js

@@ -9,9 +9,10 @@ const MongooseError = require('./');
 
 
 class OverwriteModelError extends MongooseError {
-  /*!
+  /**
    * OverwriteModel Error constructor.
    * @param {String} name
+   * @api private
    */
   constructor(name) {
     super('Cannot overwrite `' + name + '` model once compiled.');