style(schematype): touch-up jsdoc

Author: hasezoey

lib/schematype.js

@@ -134,6 +134,7 @@ SchemaType.prototype.OptionsConstructor = SchemaTypeOptions;
  * The path to this SchemaType in a Schema.
  *
  * #### Example:
+ *
  *     const schema = new Schema({ name: String });
  *     schema.path('name').path; // 'name'
  *
@@ -148,6 +149,7 @@ SchemaType.prototype.path;
  * The validators that Mongoose should run to validate properties at this SchemaType's path.
  *
  * #### Example:
+ *
  *     const schema = new Schema({ name: { type: String, required: true } });
  *     schema.path('name').validators.length; // 1, the `required` validator
  *
@@ -162,6 +164,7 @@ SchemaType.prototype.validators;
  * True if this SchemaType has a required validator. False otherwise.
  *
  * #### Example:
+ *
  *     const schema = new Schema({ name: { type: String, required: true } });
  *     schema.path('name').isRequired; // true
  *
@@ -175,8 +178,11 @@ SchemaType.prototype.validators;
 
 SchemaType.prototype.validators;
 
-/*!
- * ignore
+/**
+ * Split the current dottet path into segments
+ *
+ * @return {String[]|undefined}
+ * @api private
  */
 
 SchemaType.prototype.splitPath = function() {
@@ -351,8 +357,8 @@ SchemaType.get = function(getter) {
  *     const m2 = new M;
  *     console.log(m2.mixed); // { added: 1 }
  *
- * @param {Function|any} val the default value
- * @return {defaultValue}
+ * @param {Function|any} val The default value to set
+ * @return {Any|undefined} Returns the set default value.
  * @api public
  */
 
@@ -414,7 +420,7 @@ SchemaType.prototype.index = function(options) {
  *
  * #### Example:
  *
- *     const s = new Schema({ name: { type: String, unique: true }});
+ *     const s = new Schema({ name: { type: String, unique: true } });
  *     s.path('name').index({ unique: true });
  *
  * _NOTE: violating the constraint returns an `E11000` error from MongoDB when saving, not a Mongoose validation error._
@@ -452,8 +458,9 @@ SchemaType.prototype.unique = function(bool) {
  *
  * ### Example:
  *
- *      const s = new Schema({name : {type: String, text : true })
- *      s.path('name').index({text : true});
+ *      const s = new Schema({ name : { type: String, text : true } })
+ *      s.path('name').index({ text : true });
+ *
  * @param {Boolean} bool
  * @return {SchemaType} this
  * @api public
@@ -606,19 +613,17 @@ SchemaType.prototype.transform = function(fn) {
  *
  * #### Example:
  *
- * ```javascript
- * function capitalize (val) {
- *   if (typeof val !== 'string') val = '';
- *   return val.charAt(0).toUpperCase() + val.substring(1);
- * }
+ *     function capitalize (val) {
+ *       if (typeof val !== 'string') val = '';
+ *       return val.charAt(0).toUpperCase() + val.substring(1);
+ *     }
  *
- * // defining within the schema
- * const s = new Schema({ name: { type: String, set: capitalize }});
+ *     // defining within the schema
+ *     const s = new Schema({ name: { type: String, set: capitalize }});
  *
- * // or with the SchemaType
- * const s = new Schema({ name: String })
- * s.path('name').set(capitalize);
- * ```
+ *     // or with the SchemaType
+ *     const s = new Schema({ name: String })
+ *     s.path('name').set(capitalize);
  *
  * Setters allow you to transform the data before it gets to the raw mongodb
  * document or query.
@@ -630,76 +635,68 @@ SchemaType.prototype.transform = function(fn) {
  *
  * You can set up email lower case normalization easily via a Mongoose setter.
  *
- * ```javascript
- * function toLower(v) {
- *   return v.toLowerCase();
- * }
+ *     function toLower(v) {
+ *       return v.toLowerCase();
+ *     }
  *
- * const UserSchema = new Schema({
- *   email: { type: String, set: toLower }
- * });
+ *     const UserSchema = new Schema({
+ *       email: { type: String, set: toLower }
+ *     });
  *
- * const User = db.model('User', UserSchema);
+ *     const User = db.model('User', UserSchema);
  *
- * const user = new User({email: 'AVENUE@Q.COM'});
- * console.log(user.email); // '[email protected]'
+ *     const user = new User({email: 'AVENUE@Q.COM'});
+ *     console.log(user.email); // '[email protected]'
  *
- * // or
- * const user = new User();
- * user.email = '[email protected]';
- * console.log(user.email); // '[email protected]'
- * User.updateOne({ _id: _id }, { $set: { email: 'AVENUE@Q.COM' } }); // update to '[email protected]'
- * ```
+ *     // or
+ *     const user = new User();
+ *     user.email = '[email protected]';
+ *     console.log(user.email); // '[email protected]'
+ *     User.updateOne({ _id: _id }, { $set: { email: 'AVENUE@Q.COM' } }); // update to '[email protected]'
  *
  * As you can see above, setters allow you to transform the data before it
  * stored in MongoDB, or before executing a query.
  *
  * _NOTE: we could have also just used the built-in `lowercase: true` SchemaType option instead of defining our own function._
  *
- * ```javascript
- * new Schema({ email: { type: String, lowercase: true }})
- * ```
+ *     new Schema({ email: { type: String, lowercase: true }})
  *
  * Setters are also passed a second argument, the schematype on which the setter was defined. This allows for tailored behavior based on options passed in the schema.
  *
- * ```javascript
- * function inspector (val, priorValue, schematype) {
- *   if (schematype.options.required) {
- *     return schematype.path + ' is required';
- *   } else {
- *     return val;
- *   }
- * }
+ *     function inspector (val, priorValue, schematype) {
+ *       if (schematype.options.required) {
+ *         return schematype.path + ' is required';
+ *       } else {
+ *         return val;
+ *       }
+ *     }
  *
- * const VirusSchema = new Schema({
- *   name: { type: String, required: true, set: inspector },
- *   taxonomy: { type: String, set: inspector }
- * })
+ *     const VirusSchema = new Schema({
+ *       name: { type: String, required: true, set: inspector },
+ *       taxonomy: { type: String, set: inspector }
+ *     })
  *
- * const Virus = db.model('Virus', VirusSchema);
- * const v = new Virus({ name: 'Parvoviridae', taxonomy: 'Parvovirinae' });
+ *     const Virus = db.model('Virus', VirusSchema);
+ *     const v = new Virus({ name: 'Parvoviridae', taxonomy: 'Parvovirinae' });
  *
- * console.log(v.name);     // name is required
- * console.log(v.taxonomy); // Parvovirinae
- * ```
+ *     console.log(v.name);     // name is required
+ *     console.log(v.taxonomy); // Parvovirinae
  *
  * You can also use setters to modify other properties on the document. If
  * you're setting a property `name` on a document, the setter will run with
  * `this` as the document. Be careful, in mongoose 5 setters will also run
  * when querying by `name` with `this` as the query.
  *
- * ```javascript
- * const nameSchema = new Schema({ name: String, keywords: [String] });
- * nameSchema.path('name').set(function(v) {
- *   // Need to check if `this` is a document, because in mongoose 5
- *   // setters will also run on queries, in which case `this` will be a
- *   // mongoose query object.
- *   if (this instanceof Document && v != null) {
- *     this.keywords = v.split(' ');
- *   }
- *   return v;
- * });
- * ```
+ *     const nameSchema = new Schema({ name: String, keywords: [String] });
+ *     nameSchema.path('name').set(function(v) {
+ *       // Need to check if `this` is a document, because in mongoose 5
+ *       // setters will also run on queries, in which case `this` will be a
+ *       // mongoose query object.
+ *       if (this instanceof Document && v != null) {
+ *         this.keywords = v.split(' ');
+ *       }
+ *       return v;
+ *     });
  *
  * @param {Function} fn
  * @return {SchemaType} this
@@ -1079,6 +1076,7 @@ SchemaType.prototype.required = function(required, message) {
  * looks at to determine the foreign collection it should query.
  *
  * #### Example:
+ *
  *     const userSchema = new Schema({ name: String });
  *     const User = mongoose.model('User', userSchema);
  *
@@ -1108,6 +1106,7 @@ SchemaType.prototype.ref = function(ref) {
  *
  * @param {Object} scope the scope which callback are executed
  * @param {Boolean} init
+ * @return {Any} The Stored default value.
  * @api private
  */
 
@@ -1175,6 +1174,7 @@ SchemaType.prototype._castNullish = function _castNullish(v) {
  * @param {Object} value
  * @param {Object} scope
  * @param {Boolean} init
+ * @return {Any}
  * @api private
  */
 
@@ -1195,6 +1195,7 @@ SchemaType.prototype.applySetters = function(value, scope, init, priorVal, optio
  *
  * @param {Object} value
  * @param {Object} scope
+ * @return {Any}
  * @api private
  */
 
@@ -1239,9 +1240,12 @@ SchemaType.prototype.select = function select(val) {
 /**
  * Performs a validation of `value` using the validators declared for this SchemaType.
  *
- * @param {any} value
+ * @param {Any} value
  * @param {Function} callback
  * @param {Object} scope
+ * @param {Object} [options]
+ * @param {String} [options.path]
+ * @return {Any} If no validators, returns the output from calling `fn`, otherwise no return
  * @api public
  */
 
@@ -1352,9 +1356,11 @@ function _validate(ok, validatorProperties) {
  *
  * This method ignores the asynchronous validators.
  *
- * @param {any} value
+ * @param {Any} value
  * @param {Object} scope
- * @return {MongooseError|undefined}
+ * @param {Object} [options]
+ * @param {Object} [options.path]
+ * @return {MongooseError|null}
  * @api private
  */
 
@@ -1595,7 +1601,8 @@ SchemaType.prototype.castForQueryWrapper = function(params) {
  * Cast the given value with the given optional query operator.
  *
  * @param {String} [$conditional] query operator, like `$eq` or `$in`
- * @param {any} val
+ * @param {Any} val
+ * @return {Any}
  * @api private
  */
 
@@ -1612,9 +1619,11 @@ SchemaType.prototype.castForQuery = function($conditional, val) {
   return this._castForQuery(val);
 };
 
-/*!
+/**
  * Internal switch for runSetters
  *
+ * @param {Any} val
+ * @return {Any}
  * @api private
  */
 
@@ -1623,6 +1632,7 @@ SchemaType.prototype._castForQuery = function(val) {
 };
 
 /**
+ * Set & Get the `checkRequired` function
  * Override the function the required validator uses to check whether a value
  * passes the `required` check. Override this on the individual SchemaType.
  *
@@ -1631,8 +1641,8 @@ SchemaType.prototype._castForQuery = function(val) {
  *     // Use this to allow empty strings to pass the `required` validator
  *     mongoose.Schema.Types.String.checkRequired(v => typeof v === 'string');
  *
- * @param {Function} fn
- * @return {Function}
+ * @param {Function} [fn] If set, will overwrite the current set function
+ * @return {Function} The input `fn` or the already set function
  * @static
  * @memberOf SchemaType
  * @function checkRequired
@@ -1650,16 +1660,20 @@ SchemaType.checkRequired = function(fn) {
 /**
  * Default check for if this path satisfies the `required` validator.
  *
- * @param {any} val
+ * @param {Any} val
+ * @return {Boolean} `true` when the value is not `null`, `false` otherwise
  * @api private
  */
 
 SchemaType.prototype.checkRequired = function(val) {
   return val != null;
 };
 
-/*!
- * ignore
+/**
+ * Clone the current SchemaType
+ *
+ * @return {SchemaType} The cloned SchemaType instance
+ * @api private
  */
 
 SchemaType.prototype.clone = function() {