-
Type:
Task
-
Resolution: Won't Do
-
Priority:
Major - P3
-
None
-
Affects Version/s: None
-
Component/s: Docs
-
None
Go through all of our documentation, and where possible normalize it to reduce duplication.
Example of our code as currently written
/**
* @method
* @param {object} doc Document to insert.
* @param {object} [options] Optional settings.
* @param {(number|string)} [options.w] The write concern.
* @param {number} [options.wtimeout] The write concern timeout.
* @param {boolean} [options.j=false] Specify a journal write concern.
* @param {Collection~insertWriteOpCallback} [callback] The command result callback
* @return {Promise} returns Promise if no callback passed
*/
Collection.prototype.insertOne = function() {...}
/**
* @method
* @param {object[]} docs Documents to insert.
* @param {object} [options] Optional settings.
* @param {(number|string)} [options.w] The write concern.
* @param {number} [options.wtimeout] The write concern timeout.
* @param {boolean} [options.j=false] Specify a journal write concern.
* @param {boolean} [options.ordered=true] If true, when an insert fails, don't execute the remaining writes. If false, continue with remaining inserts when one fails.
* @param {Collection~insertWriteOpCallback} [callback] The command result callback
* @return {Promise} returns Promise if no callback passed
*/
Collection.prototype.insertMany = function() {...}
Example of new jsdoc using custom @merge-props and @merge-param tags
/**
* @typedef {object} CommonInsertOptions
* @prop {(number|string)} [w] The write concern.
* @prop {number} [wtimeout] The write concern timeout.
* @prop {boolean} [j=false] Specify a journal write concern.
*/
/**
* @typedef {object} InsertOneOptions
* @merge-props CommonInsertOptions
*/
/**
* @typedef {object} InsertManyOptions
* @merge-props CommonInsertOptions
* @prop {boolean} [ordered=true] If true, when an insert fails, don't execute the remaining writes. If false, continue with remaining inserts when one fails.
*/
/**
* @method
* @param {object} doc Document to insert.
* @merge-param {InsertOneOptions} [options] Optional settings.
* @param {Collection~insertOneWriteOpCallback} [callback] The command result callback
* @return {Promise} returns Promise if no callback passed
*/
Collection.prototype.insertOne = function() {...}
/**
* Inserts an array of documents into MongoDB. If documents passed in do not contain the **_id** field,
* one will be added to each of the documents missing it by the driver, mutating the document. This behavior
* can be overridden by setting the **forceServerObjectId** flag.
*
* @method
* @param {object[]} docs Documents to insert.
* @merge-param {InsertManyOptions} [options] Optional settings.
* @param {Collection~insertWriteOpCallback} [callback] The command result callback
* @return {Promise} returns Promise if no callback passed
*/
Collection.prototype.insertMany = function() {...}
By normalizing we can reduce the duplication of API parameters (particular offenders include BSON options, readConcern, writeConcern, and readPreferences)
