Merge pull request #12078 from hasezoey/touchupSchemaJSDOC

style(schema): touch-up jsdoc

Author: vkarpov15

lib/schema.js

@@ -79,6 +79,7 @@ let id = 0;
  * - [pluginTags](/docs/guide.html#pluginTags): array of strings - defaults to `undefined`. If set and plugin called with `tags` option, will only apply that plugin to schemas with a matching tag.
  *
  * #### Options for Nested Schemas:
+ *
  * - `excludeIndexes`: bool - defaults to `false`. If `true`, skip building indexes on this schema's paths.
  *
  * #### Note:
@@ -233,6 +234,7 @@ Object.defineProperty(Schema.prototype, 'childSchemas', {
  * You do not need to interact with this property at all to use mongoose.
  *
  * #### Example:
+ *
  *     const schema = new Schema({});
  *     schema.virtual('answer').get(() => 42);
  *
@@ -272,6 +274,7 @@ Schema.prototype.obj;
  * in this schema, and the values are instances of the SchemaType class.
  *
  * #### Example:
+ *
  *     const schema = new Schema({ name: String }, { _id: false });
  *     schema.paths; // { name: SchemaString { ... } }
  *
@@ -290,6 +293,7 @@ Schema.prototype.paths;
  * Schema as a tree
  *
  * #### Example:
+ *
  *     {
  *         '_id'     : ObjectId
  *       , 'nested'  : {
@@ -395,8 +399,8 @@ Schema.prototype._clone = function _clone(Constructor) {
  *     newSchema.path('name'); // SchemaString { ... }
  *     newSchema.path('age'); // undefined
  *
- * @param {Array} paths list of paths to pick
- * @param {Object} [options] options to pass to the schema constructor. Defaults to `this.options` if not set.
+ * @param {String[]} paths List of Paths to pick for the new Schema
+ * @param {Object} [options] Options to pass to the new Schema Constructor (same as `new Schema(.., Options)`). Defaults to `this.options` if not set.
  * @return {Schema}
  * @api public
  */
@@ -426,8 +430,8 @@ Schema.prototype.pick = function(paths, options) {
 /**
  * Returns default options for this schema, merged with `options`.
  *
- * @param {Object} options
- * @return {Object}
+ * @param {Object} [options] Options to overwrite the default options
+ * @return {Object} The merged options of `options` and the default options
  * @api private
  */
 
@@ -755,6 +759,10 @@ Schema.prototype.clearIndexes = function clearIndexes() {
  *
  *      const schema = new Schema(..);
  *      schema.methods.init = function () {} // potentially breaking
+ *
+ * @property reserved
+ * @memberOf Schema
+ * @static
  */
 
 Schema.reserved = Object.create(null);
@@ -793,8 +801,8 @@ reserved.collection = 1;
  *     schema.path('name') // returns a SchemaType
  *     schema.path('name', Number) // changes the schemaType of `name` to Number
  *
- * @param {String} path
- * @param {Object} constructor
+ * @param {String} path The name of the Path to get / set
+ * @param {Object} [obj] The Type to set the path to, if provided the path will be SET, otherwise the path will be GET
  * @api public
  */
 
@@ -1059,6 +1067,7 @@ Object.defineProperty(Schema.prototype, 'base', {
  *
  * @param {String} path
  * @param {Object} obj constructor
+ * @param {Object} options
  * @api private
  */
 
@@ -1316,6 +1325,7 @@ Schema.prototype.eachPath = function(fn) {
  * Returns an Array of path strings that are required by this schema.
  *
  * #### Example:
+ *
  *     const s = new Schema({
  *       name: { type: String, required: true },
  *       age: { type: String, required: true },
@@ -1324,7 +1334,7 @@ Schema.prototype.eachPath = function(fn) {
  *     s.requiredPaths(); // [ 'age', 'name' ]
  *
  * @api public
- * @param {Boolean} invalidate refresh the cache
+ * @param {Boolean} invalidate Refresh the cache
  * @return {Array}
  */
 
@@ -1673,8 +1683,14 @@ Schema.prototype.post = function(name) {
  *     s.plugin(schema => console.log(schema.path('name').path));
  *     mongoose.model('Test', s); // Prints 'name'
  *
- * @param {Function} plugin callback
- * @param {Object} [opts]
+ * Or with Options:
+ *
+ *     const s = new Schema({ name: String });
+ *     s.plugin((schema, opts) => console.log(opts.text, schema.path('name').path), { text: "Schema Path Name:" });
+ *     mongoose.model('Test', s); // Prints 'Schema Path Name: name'
+ *
+ * @param {Function} plugin The Plugin's callback
+ * @param {Object} [opts] Options to pass to the plugin
  * @see plugins
  * @api public
  */
@@ -1722,13 +1738,14 @@ Schema.prototype.plugin = function(fn, opts) {
  *     });
  *
  *     // later
+ *     const fizz = new Kitty;
  *     fizz.purr();
  *     fizz.scratch();
  *
  * NOTE: `Schema.method()` adds instance methods to the `Schema.methods` object. You can also add instance methods directly to the `Schema.methods` object as seen in the [guide](/docs/guide.html#methods)
  *
- * @param {String|Object} method name
- * @param {Function} [fn]
+ * @param {String|Object} name The Method Name for a single function, or a Object of "string-function" pairs.
+ * @param {Function} [fn] The Function in a single-function definition.
  * @api public
  */
 
@@ -1759,10 +1776,21 @@ Schema.prototype.method = function(name, fn, options) {
  *     const Drink = mongoose.model('Drink', schema);
  *     await Drink.findByName('LaCroix');
  *
+ * If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as methods.
+ *
+ *     schema.static({
+ *         findByName: function () {..}
+ *       , findByCost: function () {..}
+ *     });
+ *
+ *     const Drink = mongoose.model('Drink', schema);
+ *     await Drink.findByName('LaCroix');
+ *     await Drink.findByCost(3);
+ *
  * If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as statics.
  *
- * @param {String|Object} name
- * @param {Function} [fn]
+ * @param {String|Object} name The Method Name for a single function, or a Object of "string-function" pairs.
+ * @param {Function} [fn] The Function in a single-function definition.
  * @api public
  * @see Statics /docs/guide.html#statics
  */
@@ -1785,7 +1813,7 @@ Schema.prototype.static = function(name, fn) {
  *
  *     schema.index({ first: 1, last: -1 })
  *
- * @param {Object} fields
+ * @param {Object} fields The Fields to index, with the order, available values: `1 | -1 | '2d' | '2dsphere' | 'geoHaystack' | 'hashed' | 'text'`
  * @param {Object} [options] Options to pass to [MongoDB driver's `createIndex()` function](https://mongodb.github.io/node-mongodb-native/2.0/api/Collection.html#createIndex)
  * @param {String | number} [options.expires=null] Mongoose-specific syntactic sugar, uses [ms](https://www.npmjs.com/package/ms) to convert `expires` option into seconds for the `expireAfterSeconds` in the above link.
  * @api public
@@ -1812,8 +1840,8 @@ Schema.prototype.index = function(fields, options) {
  *     schema.set('strict', false); // Sets 'strict' to false
  *     schema.set('strict'); // 'false'
  *
- * @param {String} key option name
- * @param {Object} [value] if not passed, the current option value is returned
+ * @param {String} key The name of the option to set the value to
+ * @param {Object} [value] The value to set the option to, if not passed, the option will be reset to default
  * @see Schema ./
  * @api public
  */
@@ -1861,7 +1889,7 @@ Schema.prototype.set = function(key, value, _tags) {
  *     schema.set('strict', false);
  *     schema.get('strict'); // false
  *
- * @param {String} key option name
+ * @param {String} key The name of the Option to get the current value for
  * @api public
  * @return {Any} the option's value
  */
@@ -1927,7 +1955,7 @@ Schema.prototype.indexes = function() {
 /**
  * Creates a virtual type with the given name.
  *
- * @param {String} name
+ * @param {String} name The name of the Virtual
  * @param {Object} [options]
  * @param {String|Model} [options.ref] model name or model instance. Marks this as a [populate virtual](/docs/populate.html#populate-virtuals).
  * @param {String|Function} [options.localField] Required for populate virtuals. See [populate virtual docs](/docs/populate.html#populate-virtuals) for more information.
@@ -2045,8 +2073,8 @@ Schema.prototype.virtual = function(name, options) {
 /**
  * Returns the virtual type with the given `name`.
  *
- * @param {String} name
- * @return {VirtualType}
+ * @param {String} name The name of the Virtual to get
+ * @return {VirtualType|null}
  */
 
 Schema.prototype.virtualpath = function(name) {
@@ -2063,7 +2091,13 @@ Schema.prototype.virtualpath = function(name) {
  *     schema.path('name'); // Undefined
  *     schema.path('age'); // SchemaNumber { ... }
  *
- * @param {String|Array} path
+ * Or as a Array:
+ *
+ *     schema.remove(['name', 'age']);
+ *     schema.path('name'); // Undefined
+ *     schema.path('age'); // Undefined
+ *
+ * @param {String|Array} path The Path(s) to remove
  * @return {Schema} the Schema instance
  * @api public
  */
@@ -2151,7 +2185,7 @@ function _deletePath(schema, name) {
  * userSchema.loadClass(UserClass);
  * ```
  *
- * @param {Function} model
+ * @param {Function} model The Class to load
  * @param {Boolean} [virtualsOnly] if truthy, only pulls virtuals from the class, not methods or statics
  */
 Schema.prototype.loadClass = function(model, virtualsOnly) {