docs: add Buffer, Decimal128, Map to docs

Fix #11971
Automattic · Jul 2, 2022 · a55d388 · a55d388
1 parent c6a92ce
commit a55d388
Show file tree

Hide file tree

Showing 4 changed files with 103 additions and 32 deletions.
diff --git a/docs/source/api.js b/docs/source/api.js
@@ -33,7 +33,10 @@ const files = [
   'lib/options/SchemaStringOptions.js',
   'lib/types/DocumentArray/methods/index.js',
   'lib/types/subdocument.js',
-  'lib/types/ArraySubdocument.js'
+  'lib/types/ArraySubdocument.js',
+  'lib/types/buffer.js',
+  'lib/types/decimal128.js',
+  'lib/types/map.js'
 ];
 
 module.exports = {

diff --git a/lib/types/buffer.js b/lib/types/buffer.js
@@ -70,7 +70,7 @@ MongooseBuffer.mixin = {
    *
    * @api private
    * @property _subtype
-   * @receiver MongooseBuffer
+   * @memberOf MongooseBuffer
    */
 
   _subtype: undefined,
@@ -80,7 +80,7 @@ MongooseBuffer.mixin = {
    *
    * @api private
    * @method _markModified
-   * @receiver MongooseBuffer
+   * @memberOf MongooseBuffer
    */
 
   _markModified: function() {
@@ -97,7 +97,7 @@ MongooseBuffer.mixin = {
    *
    * @api public
    * @method write
-   * @receiver MongooseBuffer
+   * @memberOf MongooseBuffer
    */
 
   write: function() {
@@ -120,7 +120,7 @@ MongooseBuffer.mixin = {
    * @return {Number} The number of bytes copied.
    * @param {Buffer} target
    * @method copy
-   * @receiver MongooseBuffer
+   * @memberOf MongooseBuffer
    */
 
   copy: function(target) {
@@ -161,24 +161,22 @@ MongooseBuffer.mixin = {
 /**
  * Converts this buffer to its Binary type representation.
  *
- * ####SubTypes:
- *
- *   const bson = require('bson')
- *   bson.BSON_BINARY_SUBTYPE_DEFAULT
- *   bson.BSON_BINARY_SUBTYPE_FUNCTION
- *   bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY
- *   bson.BSON_BINARY_SUBTYPE_UUID
- *   bson.BSON_BINARY_SUBTYPE_MD5
- *   bson.BSON_BINARY_SUBTYPE_USER_DEFINED
- *
- *   doc.buffer.toObject(bson.BSON_BINARY_SUBTYPE_USER_DEFINED);
+ * #### SubTypes:
+ *     const bson = require('bson')
+ *     bson.BSON_BINARY_SUBTYPE_DEFAULT
+ *     bson.BSON_BINARY_SUBTYPE_FUNCTION
+ *     bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY
+ *     bson.BSON_BINARY_SUBTYPE_UUID
+ *     bson.BSON_BINARY_SUBTYPE_MD5
+ *     bson.BSON_BINARY_SUBTYPE_USER_DEFINED
+ *     doc.buffer.toObject(bson.BSON_BINARY_SUBTYPE_USER_DEFINED);
  *
  * @see https://bsonspec.org/#/specification
  * @param {Hex} [subtype]
  * @return {Binary}
  * @api public
  * @method toObject
- * @receiver MongooseBuffer
+ * @memberOf MongooseBuffer
  */
 
 MongooseBuffer.mixin.toObject = function(options) {
@@ -196,7 +194,7 @@ MongooseBuffer.mixin.$toObject = MongooseBuffer.mixin.toObject;
  * @return {Binary}
  * @api public
  * @method toBSON
- * @receiver MongooseBuffer
+ * @memberOf MongooseBuffer
  */
 
 MongooseBuffer.mixin.toBSON = function() {
@@ -209,7 +207,7 @@ MongooseBuffer.mixin.toBSON = function() {
  * @param {Buffer} other
  * @return {Boolean}
  * @method equals
- * @receiver MongooseBuffer
+ * @memberOf MongooseBuffer
  */
 
 MongooseBuffer.mixin.equals = function(other) {
@@ -233,23 +231,23 @@ MongooseBuffer.mixin.equals = function(other) {
 /**
  * Sets the subtype option and marks the buffer modified.
  *
- * ####SubTypes:
+ * #### SubTypes:
  *
- *   const bson = require('bson')
- *   bson.BSON_BINARY_SUBTYPE_DEFAULT
- *   bson.BSON_BINARY_SUBTYPE_FUNCTION
- *   bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY
- *   bson.BSON_BINARY_SUBTYPE_UUID
- *   bson.BSON_BINARY_SUBTYPE_MD5
- *   bson.BSON_BINARY_SUBTYPE_USER_DEFINED
+ *     const bson = require('bson')
+ *     bson.BSON_BINARY_SUBTYPE_DEFAULT
+ *     bson.BSON_BINARY_SUBTYPE_FUNCTION
+ *     bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY
+ *     bson.BSON_BINARY_SUBTYPE_UUID
+ *     bson.BSON_BINARY_SUBTYPE_MD5
+ *     bson.BSON_BINARY_SUBTYPE_USER_DEFINED
  *
- *   doc.buffer.subtype(bson.BSON_BINARY_SUBTYPE_UUID);
+ *     doc.buffer.subtype(bson.BSON_BINARY_SUBTYPE_UUID);
  *
  * @see https://bsonspec.org/#/specification
  * @param {Hex} subtype
  * @api public
  * @method subtype
- * @receiver MongooseBuffer
+ * @memberOf MongooseBuffer
  */
 
 MongooseBuffer.mixin.subtype = function(subtype) {

diff --git a/lib/types/decimal128.js b/lib/types/decimal128.js
@@ -1,11 +1,11 @@
 /**
- * ObjectId type constructor
+ * Decimal128 type constructor
  *
  * #### Example
  *
- *     const id = new mongoose.Types.ObjectId;
+ *     const id = new mongoose.Types.Decimal128('3.1415');
  *
- * @constructor ObjectId
+ * @constructor Decimal128
  */
 
 'use strict';

diff --git a/lib/types/map.js b/lib/types/map.js
@@ -42,6 +42,14 @@ class MongooseMap extends Map {
     super.set(key, value);
   }
 
+  /**
+   * Overwrites native Map's `get()` function to support Mongoose getters.
+   *
+   * @api public
+   * @method get
+   * @memberOf Map
+   */
+
   get(key, options) {
     if (isBsonType(key, 'ObjectID')) {
       key = key.toString();
@@ -54,6 +62,20 @@ class MongooseMap extends Map {
     return this.$__schemaType.applyGetters(super.get(key), this.$__parent);
   }
 
+  /**
+   * Overwrites native Map's `set()` function to support setters, `populate()`,
+   * and change tracking. Note that Mongoose maps _only_ support strings and
+   * ObjectIds as keys.
+   *
+   * #### Example:
+   *     doc.myMap.set('test', 42); // works
+   *     doc.myMap.set({ obj: 42 }, 42); // Throws "Mongoose maps only support string keys"
+   *
+   * @api public
+   * @method set
+   * @memberOf Map
+   */
+
   set(key, value) {
     if (isBsonType(key, 'ObjectID')) {
       key = key.toString();
@@ -108,6 +130,14 @@ class MongooseMap extends Map {
     }
   }
 
+  /**
+   * Overwrites native Map's `clear()` function to support change tracking.
+   *
+   * @api public
+   * @method clear
+   * @memberOf Map
+   */
+
   clear() {
     super.clear();
     const parent = this.$__parent;
@@ -116,6 +146,14 @@ class MongooseMap extends Map {
     }
   }
 
+  /**
+   * Overwrites native Map's `delete()` function to support change tracking.
+   *
+   * @api public
+   * @method delete
+   * @memberOf Map
+   */
+
   delete(key) {
     if (isBsonType(key, 'ObjectID')) {
       key = key.toString();
@@ -125,6 +163,14 @@ class MongooseMap extends Map {
     super.delete(key);
   }
 
+  /**
+   * Converts this map to a native JavaScript Map so the MongoDB driver can serialize it.
+   *
+   * @api public
+   * @method toBSON
+   * @memberOf Map
+   */
+
   toBSON() {
     return new Map(this);
   }
@@ -146,6 +192,21 @@ class MongooseMap extends Map {
     return this.constructor.prototype.toObject.apply(this, arguments);
   }
 
+  /**
+   * Converts this map to a native JavaScript Map for `JSON.stringify()`. Set
+   * the `flattenMaps` option to convert this map to a POJO instead.
+   *
+   * #### Example:
+   *     doc.myMap.toJSON() instanceof Map; // true
+   *     doc.myMap.toJSON({ flattenMaps: true }) instanceof Map; // false
+   *
+   * @api public
+   * @method toJSON
+   * @param {Object} [options]
+   * @param {Boolean} [options.flattenMaps=false] set to `true` to convert the map to a POJO rather than a native JavaScript map
+   * @memberOf Map
+   */
+
   toJSON(options) {
     if (typeof (options && options.flattenMaps) === 'boolean' ? options.flattenMaps : true) {
       const ret = {};
@@ -209,6 +270,15 @@ Object.defineProperty(MongooseMap.prototype, '$__schemaType', {
   configurable: false
 });
 
+/**
+ * Set to `true` for all Mongoose map instances
+ *
+ * @api public
+ * @property $isMongooseMap
+ * @memberOf Map
+ * @instance
+ */
+
 Object.defineProperty(MongooseMap.prototype, '$isMongooseMap', {
   enumerable: false,
   writable: false,