docs: add documentarraypath to API docs, including DocumentArrayPath#discriminator()

Fix #8164

Author: vkarpov15

docs/source/api.js

@@ -24,6 +24,7 @@ const files = [
   'lib/virtualtype.js',
   'lib/error/index.js',
   'lib/types/core_array.js',
+  'lib/schema/documentarray.js',
   'lib/schema/SingleNestedPath.js',
   'lib/options/SchemaTypeOptions.js',
   'lib/options/SchemaArrayOptions.js',
@@ -63,6 +64,9 @@ function parse() {
     if (name === 'core_array') {
       name = 'array';
     }
+    if (name === 'documentarray') {
+      name = 'DocumentArrayPath';
+    }
     const data = {
       name: name.charAt(0).toUpperCase() === name.charAt(0) ? name : name.charAt(0).toUpperCase() + name.substr(1),
       props: []

lib/model.js

@@ -1066,7 +1066,7 @@ Model.exists = function exists(filter, options, callback) {
  *
  * @param {String} name discriminator model name
  * @param {Schema} schema discriminator model schema
- * @param {String} value the string stored in the `discriminatorKey` property
+ * @param {String} [value] the string stored in the `discriminatorKey` property. If not specified, Mongoose uses the `name` parameter.
  * @api public
  */
 

lib/schema/SingleNestedPath.js

@@ -274,17 +274,18 @@ SingleNestedPath.prototype.doValidateSync = function(value, scope, options) {
  *     const shapeSchema = Schema({ name: String }, { discriminatorKey: 'kind' });
  *     const schema = Schema({ shape: shapeSchema });
  *
- *     const singleNestedPath = parentSchema.path('child');
+ *     const singleNestedPath = parentSchema.path('shape');
  *     singleNestedPath.discriminator('Circle', Schema({ radius: Number }));
  *
  * @param {String} name
  * @param {Schema} schema fields to add to the schema for instances of this sub-class
+ * @param {String} [value] the string stored in the `discriminatorKey` property. If not specified, Mongoose uses the `name` parameter.
  * @see discriminators /docs/discriminators.html
  * @api public
  */
 
-SingleNestedPath.prototype.discriminator = function(name, schema, tiedValue) {
-  discriminator(this.caster, name, schema, tiedValue);
+SingleNestedPath.prototype.discriminator = function(name, schema, value) {
+  discriminator(this.caster, name, schema, value);
 
   this.caster.discriminators[name] = _createConstructor(schema, this.caster);
 

lib/schema/documentarray.js

@@ -29,7 +29,7 @@ let Subdocument;
  * @api public
  */
 
-function DocumentArray(key, schema, options, schemaOptions) {
+function DocumentArrayPath(key, schema, options, schemaOptions) {
   const EmbeddedDocument = _createConstructor(schema, options);
   EmbeddedDocument.prototype.$basePath = key;
 
@@ -62,24 +62,23 @@ function DocumentArray(key, schema, options, schemaOptions) {
  *
  * @api public
  */
-DocumentArray.schemaName = 'DocumentArray';
+DocumentArrayPath.schemaName = 'DocumentArray';
 
 /**
  * Options for all document arrays.
  *
  * - `castNonArrays`: `true` by default. If `false`, Mongoose will throw a CastError when a value isn't an array. If `true`, Mongoose will wrap the provided value in an array before casting.
  *
- * @static options
  * @api public
  */
 
-DocumentArray.options = { castNonArrays: true };
+DocumentArrayPath.options = { castNonArrays: true };
 
 /*!
  * Inherits from ArrayType.
  */
-DocumentArray.prototype = Object.create(ArrayType.prototype);
-DocumentArray.prototype.constructor = DocumentArray;
+DocumentArrayPath.prototype = Object.create(ArrayType.prototype);
+DocumentArrayPath.prototype.constructor = DocumentArrayPath;
 
 /*!
  * Ignore
@@ -122,11 +121,24 @@ function _createConstructor(schema, options, baseClass) {
   return EmbeddedDocument;
 }
 
-/*!
- * Ignore
+/**
+ * Adds a discriminator to this document array.
+ *
+ * ####Example:
+ *     const shapeSchema = Schema({ name: String }, { discriminatorKey: 'kind' });
+ *     const schema = Schema({ shapes: [shapeSchema] });
+ *
+ *     const docArrayPath = parentSchema.path('shapes');
+ *     docArrayPath.discriminator('Circle', Schema({ radius: Number }));
+ *
+ * @param {String} name
+ * @param {Schema} schema fields to add to the schema for instances of this sub-class
+ * @param {String} [value] the string stored in the `discriminatorKey` property. If not specified, Mongoose uses the `name` parameter.
+ * @see discriminators /docs/discriminators.html
+ * @api public
  */
 
-DocumentArray.prototype.discriminator = function(name, schema, tiedValue) {
+DocumentArrayPath.prototype.discriminator = function(name, schema, tiedValue) {
   if (typeof name === 'function') {
     name = utils.getFunctionName(name);
   }
@@ -155,7 +167,7 @@ DocumentArray.prototype.discriminator = function(name, schema, tiedValue) {
  * @api private
  */
 
-DocumentArray.prototype.doValidate = function(array, fn, scope, options) {
+DocumentArrayPath.prototype.doValidate = function(array, fn, scope, options) {
   // lazy load
   MongooseDocumentArray || (MongooseDocumentArray = require('../types/documentarray'));
 
@@ -231,7 +243,7 @@ DocumentArray.prototype.doValidate = function(array, fn, scope, options) {
  * @api private
  */
 
-DocumentArray.prototype.doValidateSync = function(array, scope) {
+DocumentArrayPath.prototype.doValidateSync = function(array, scope) {
   const schemaTypeError = SchemaType.prototype.doValidateSync.call(this, array, scope);
   if (schemaTypeError != null) {
     schemaTypeError.$isArrayValidatorError = true;
@@ -277,7 +289,7 @@ DocumentArray.prototype.doValidateSync = function(array, scope) {
  * ignore
  */
 
-DocumentArray.prototype.getDefault = function(scope) {
+DocumentArrayPath.prototype.getDefault = function(scope) {
   let ret = typeof this.defaultValue === 'function'
     ? this.defaultValue.call(scope)
     : this.defaultValue;
@@ -316,7 +328,7 @@ DocumentArray.prototype.getDefault = function(scope) {
  * @api private
  */
 
-DocumentArray.prototype.cast = function(value, doc, init, prev, options) {
+DocumentArrayPath.prototype.cast = function(value, doc, init, prev, options) {
   // lazy load
   MongooseDocumentArray || (MongooseDocumentArray = require('../types/documentarray'));
 
@@ -326,7 +338,7 @@ DocumentArray.prototype.cast = function(value, doc, init, prev, options) {
   const _opts = { transform: false, virtuals: false };
 
   if (!Array.isArray(value)) {
-    if (!init && !DocumentArray.options.castNonArrays) {
+    if (!init && !DocumentArrayPath.options.castNonArrays) {
       throw new CastError('DocumentArray', util.inspect(value), this.path);
     }
     // gh-2442 mark whole array as modified if we're initializing a doc from
@@ -416,7 +428,7 @@ DocumentArray.prototype.cast = function(value, doc, init, prev, options) {
  * ignore
  */
 
-DocumentArray.prototype.clone = function() {
+DocumentArrayPath.prototype.clone = function() {
   const options = Object.assign({}, this.options);
   const schematype = new this.constructor(this.path, this.schema, options, this.schemaOptions);
   schematype.validators = this.validators.slice();
@@ -429,7 +441,7 @@ DocumentArray.prototype.clone = function() {
  * Scopes paths selected in a query to this array.
  * Necessary for proper default application of subdocument values.
  *
- * @param {DocumentArray} array - the array to scope `fields` paths
+ * @param {DocumentArrayPath} array - the array to scope `fields` paths
  * @param {Object|undefined} fields - the root fields selected in the query
  * @param {Boolean|undefined} init - if we are being created part of a query result
  */
@@ -469,4 +481,4 @@ function scopePaths(array, fields, init) {
  * Module exports.
  */
 
-module.exports = DocumentArray;
+module.exports = DocumentArrayPath;