docs: add schema options to API docs

Fix #8012
Automattic · Oct 12, 2019 · 973b1e0 · 973b1e0
1 parent cdfb507
commit 973b1e0
Show file tree

Hide file tree

Showing 12 changed files with 140 additions and 25 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
  */