From 973b1e07014950b5c7d3f8af5ea9a61f485e1711 Mon Sep 17 00:00:00 2001 From: Valeri Karpov Date: Sat, 12 Oct 2019 15:25:18 -0400 Subject: [PATCH] docs: add schema options to API docs Fix #8012 --- docs/api.pug | 19 +++++++++--------- docs/api_split.pug | 29 ++++++++++++++-------------- docs/source/api.js | 16 ++++++++++++++- lib/index.js | 9 +++++++++ lib/options/SchemaArrayOptions.js | 13 +++++++++++++ lib/options/SchemaBufferOptions.js | 13 +++++++++++++ lib/options/SchemaDateOptions.js | 13 +++++++++++++ lib/options/SchemaNumberOptions.js | 13 +++++++++++++ lib/options/SchemaObjectIdOptions.js | 13 +++++++++++++ lib/options/SchemaStringOptions.js | 13 +++++++++++++ lib/options/SchemaTypeOptions.js | 12 ++++++++++++ lib/schematype.js | 2 +- 12 files changed, 140 insertions(+), 25 deletions(-) diff --git a/docs/api.pug b/docs/api.pug index 42c6c5a1376..7644708ca4f 100644 --- a/docs/api.pug +++ b/docs/api.pug @@ -16,15 +16,16 @@ block content div.api-nav div.api-nav-content each item in docs - div.nav-item(id='nav-' + item.name) - div.nav-item-title - a(href='./api/' + item.name.toLowerCase() + '.html') - | #{item.name} - ul.nav-item-sub - each prop in item.props - li - a(href='./api/' + item.name.toLowerCase() + '.html#' + prop.anchorId) - | #{prop.string} + - if (!item.hideFromNav) + div.nav-item(id='nav-' + item.name) + div.nav-item-title + a(href='./api/' + item.name.toLowerCase() + '.html') + | #{item.name} + ul.nav-item-sub + each prop in item.props + li + a(href='./api/' + item.name.toLowerCase() + '.html#' + prop.anchorId) + | #{prop.string} each item in docs hr.separate-api diff --git a/docs/api_split.pug b/docs/api_split.pug index 2ffc93e3608..021ca601bd6 100644 --- a/docs/api_split.pug +++ b/docs/api_split.pug @@ -25,20 +25,21 @@ block content div.api-nav div.api-nav-content each item in docs - div.nav-item(id='nav-' + item.name) - - if (item.name === name) - div.nav-item-title(style="font-weight: bold") - a(href=item.name.toLowerCase() + '.html') - | #{item.name} - ul.nav-item-sub - each prop in item.props - li - a(href='#' + prop.anchorId) - | #{prop.string} - - else - div.nav-item-title - a(href=item.name.toLowerCase() + '.html') - | #{item.name} + - if (!item.hideFromNav || item.name === name) + div.nav-item(id='nav-' + item.name) + - if (item.name === name) + div.nav-item-title(style="font-weight: bold") + a(href=item.name.toLowerCase() + '.html') + | #{item.name} + ul.nav-item-sub + each prop in item.props + li + a(href='#' + prop.anchorId) + | #{prop.string} + - else + div.nav-item-title + a(href=item.name.toLowerCase() + '.html') + | #{item.name} div.api-content ul diff --git a/docs/source/api.js b/docs/source/api.js index 8ef499a6ca3..011ab45fe45 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -24,7 +24,14 @@ const files = [ 'lib/virtualtype.js', 'lib/error/index.js', 'lib/types/core_array.js', - 'lib/schema/SingleNestedPath.js' + 'lib/schema/SingleNestedPath.js', + 'lib/options/SchemaTypeOptions.js', + 'lib/options/SchemaArrayOptions.js', + 'lib/options/SchemaBufferOptions.js', + 'lib/options/SchemaDateOptions.js', + 'lib/options/SchemaNumberOptions.js', + 'lib/options/SchemaObjectIdOptions.js', + 'lib/options/SchemaStringOptions.js' ]; module.exports = { @@ -83,6 +90,9 @@ function parse() { 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; @@ -164,6 +174,10 @@ function parse() { } }); + if (props.file.startsWith('lib/options')) { + data.hideFromNav = true; + } + out.push(data); } } diff --git a/lib/index.js b/lib/index.js index ad89dffc536..6fbfb932e5c 100644 --- a/lib/index.js +++ b/lib/index.js @@ -1015,6 +1015,15 @@ Mongoose.prototype.now = function now() { return new Date(); }; Mongoose.prototype.CastError = require('./error/cast'); +/** + * The constructor used for schematype options + * + * @method SchemaTypeOptions + * @api public + */ + +Mongoose.prototype.SchemaTypeOptions = require('./options/SchemaTypeOptions'); + /** * The [node-mongodb-native](https://github.com/mongodb/node-mongodb-native) driver Mongoose uses. * diff --git a/lib/options/SchemaArrayOptions.js b/lib/options/SchemaArrayOptions.js index 330ac2db5e9..5ad6fe9060a 100644 --- a/lib/options/SchemaArrayOptions.js +++ b/lib/options/SchemaArrayOptions.js @@ -2,6 +2,19 @@ const SchemaTypeOptions = require('./SchemaTypeOptions'); +/** + * The options defined on an Array schematype. + * + * ####Example: + * + * const schema = new Schema({ tags: [String] }); + * schema.path('tags').options; // SchemaArrayOptions instance + * + * @api public + * @inherits SchemaTypeOptions + * @constructor SchemaArrayOptions + */ + class SchemaArrayOptions extends SchemaTypeOptions {} const opts = { diff --git a/lib/options/SchemaBufferOptions.js b/lib/options/SchemaBufferOptions.js index 4ee8957ba2a..d5cb9bda23c 100644 --- a/lib/options/SchemaBufferOptions.js +++ b/lib/options/SchemaBufferOptions.js @@ -2,6 +2,19 @@ const SchemaTypeOptions = require('./SchemaTypeOptions'); +/** + * The options defined on a Buffer schematype. + * + * ####Example: + * + * const schema = new Schema({ bitmap: Buffer }); + * schema.path('bitmap').options; // SchemaBufferOptions instance + * + * @api public + * @inherits SchemaTypeOptions + * @constructor SchemaBufferOptions + */ + class SchemaBufferOptions extends SchemaTypeOptions {} const opts = { diff --git a/lib/options/SchemaDateOptions.js b/lib/options/SchemaDateOptions.js index 5334e5f66c3..5a78ea44aeb 100644 --- a/lib/options/SchemaDateOptions.js +++ b/lib/options/SchemaDateOptions.js @@ -2,6 +2,19 @@ const SchemaTypeOptions = require('./SchemaTypeOptions'); +/** + * The options defined on a Date schematype. + * + * ####Example: + * + * const schema = new Schema({ startedAt: Date }); + * schema.path('startedAt').options; // SchemaDateOptions instance + * + * @api public + * @inherits SchemaTypeOptions + * @constructor SchemaDateOptions + */ + class SchemaDateOptions extends SchemaTypeOptions {} const opts = { diff --git a/lib/options/SchemaNumberOptions.js b/lib/options/SchemaNumberOptions.js index 6bb57e3cd98..4b016bebd0d 100644 --- a/lib/options/SchemaNumberOptions.js +++ b/lib/options/SchemaNumberOptions.js @@ -2,6 +2,19 @@ const SchemaTypeOptions = require('./SchemaTypeOptions'); +/** + * The options defined on a Number schematype. + * + * ####Example: + * + * const schema = new Schema({ count: Number }); + * schema.path('count').options; // SchemaNumberOptions instance + * + * @api public + * @inherits SchemaTypeOptions + * @constructor SchemaNumberOptions + */ + class SchemaNumberOptions extends SchemaTypeOptions {} const opts = { diff --git a/lib/options/SchemaObjectIdOptions.js b/lib/options/SchemaObjectIdOptions.js index 67ecc8a863d..948116e04ae 100644 --- a/lib/options/SchemaObjectIdOptions.js +++ b/lib/options/SchemaObjectIdOptions.js @@ -2,6 +2,19 @@ const SchemaTypeOptions = require('./SchemaTypeOptions'); +/** + * The options defined on an ObjectId schematype. + * + * ####Example: + * + * const schema = new Schema({ testId: mongoose.ObjectId }); + * schema.path('testId').options; // SchemaObjectIdOptions instance + * + * @api public + * @inherits SchemaTypeOptions + * @constructor SchemaObjectIdOptions + */ + class SchemaObjectIdOptions extends SchemaTypeOptions {} const opts = { diff --git a/lib/options/SchemaStringOptions.js b/lib/options/SchemaStringOptions.js index 54ca35edfba..72271828224 100644 --- a/lib/options/SchemaStringOptions.js +++ b/lib/options/SchemaStringOptions.js @@ -2,6 +2,19 @@ const SchemaTypeOptions = require('./SchemaTypeOptions'); +/** + * The options defined on a string schematype. + * + * ####Example: + * + * const schema = new Schema({ name: String }); + * schema.path('name').options; // SchemaStringOptions instance + * + * @api public + * @inherits SchemaTypeOptions + * @constructor SchemaStringOptions + */ + class SchemaStringOptions extends SchemaTypeOptions {} const opts = { diff --git a/lib/options/SchemaTypeOptions.js b/lib/options/SchemaTypeOptions.js index 51bfd6b571b..6b7444f1333 100644 --- a/lib/options/SchemaTypeOptions.js +++ b/lib/options/SchemaTypeOptions.js @@ -2,6 +2,18 @@ const utils = require('../utils'); +/** + * The options defined on a schematype. + * + * ####Example: + * + * const schema = new Schema({ name: String }); + * schema.path('name').options instanceof mongoose.SchemaTypeOptions; // true + * + * @api public + * @constructor SchemaTypeOptions + */ + class SchemaTypeOptions { constructor(obj) { if (obj == null) { diff --git a/lib/schematype.js b/lib/schematype.js index fbce0e0dce6..ed5b6738ec0 100644 --- a/lib/schematype.js +++ b/lib/schematype.js @@ -29,7 +29,7 @@ const ValidatorError = MongooseError.ValidatorError; * schema.path('name') instanceof SchemaType; // true * * @param {String} path - * @param {Object} [options] + * @param {SchemaTypeOptions} [options] See [SchemaTypeOptions docs](/docs/api/schematypeoptions.html) * @param {String} [instance] * @api public */