NODE-473 NODE-545 improved API documentation

Author: christkv

conf.json

@@ -21,6 +21,7 @@
       "lib/bulk/ordered.js",
       "lib/bulk/unordered.js",
       "lib/gridfs/grid_store.js",
+      "node_modules/mongodb-core/lib/error.js",
       "node_modules/mongodb-core/lib/connection/logger.js",
       "node_modules/bson/lib/bson/binary.js",
       "node_modules/bson/lib/bson/code.js",

lib/collection.js

@@ -350,7 +350,7 @@ Collection.prototype.find = function() {
  * @param {boolean} [options.j=false] Specify a journal write concern.
  * @param {boolean} [options.serializeFunctions=false] Serialize functions on any object.
  * @param {boolean} [options.forceServerObjectId=false] Force server to assign _id values instead of driver.
- * @param {Collection~writeOpCallback} [callback] The command result callback
+ * @param {Collection~insertWriteOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.insertOne = function(doc, options, callback) {
@@ -413,7 +413,7 @@ var mapInserManyResults = function(docs, r) {
  * @param {boolean} [options.j=false] Specify a journal write concern.
  * @param {boolean} [options.serializeFunctions=false] Serialize functions on any object.
  * @param {boolean} [options.forceServerObjectId=false] Force server to assign _id values instead of driver.
- * @param {Collection~writeOpCallback} [callback] The command result callback
+ * @param {Collection~insertWriteOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.insertMany = function(docs, options, callback) {
@@ -641,6 +641,24 @@ var insertDocuments = function(self, docs, options, callback) {
  * @param {Collection~WriteOpResult} result The result object if the command was executed successfully.
  */
 
+/**
+ * @typedef {Object} Collection~insertWriteOpResult
+ * @property {Number} insertedCount The total amount of documents inserted.
+ * @property {object[]} ops All the documents inserted using insertOne/insertMany/replaceOne. Documents contain the _id field if forceServerObjectId == false for insertOne/insertMany
+ * @property {ObjectId[]} insertedIds All the generated _id's for the inserted documents.
+ * @property {object} connection The connection object used for the operation.
+ * @property {object} result The raw command result object returned from MongoDB (content might vary by server version).
+ * @property {Number} result.ok Is 1 if the command executed correctly.
+ * @property {Number} result.n The total count of documents inserted.
+ */
+
+/**
+ * The callback format for inserts
+ * @callback Collection~insertWriteOpCallback
+ * @param {MongoError} error An error instance representing the error during the execution.
+ * @param {Collection~insertWriteOpResult} result The result object if the command was executed successfully.
+ */
+
 /**
  * Inserts a single document or a an array of documents into MongoDB.
  * @method
@@ -651,7 +669,7 @@ var insertDocuments = function(self, docs, options, callback) {
  * @param {boolean} [options.j=false] Specify a journal write concern.
  * @param {boolean} [options.serializeFunctions=false] Serialize functions on any object.
  * @param {boolean} [options.forceServerObjectId=false] Force server to assign _id values instead of driver.
- * @param {Collection~writeOpCallback} [callback] The command result callback
+ * @param {Collection~insertWriteOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  * @deprecated Use insertOne, insertMany or bulkWrite
  */
@@ -668,6 +686,27 @@ Collection.prototype.insert = function(docs, options, callback) {
   return this.insertMany(docs, options, callback);
 }
 
+/**
+ * @typedef {Object} Collection~updateWriteOpResult
+ * @property {Object} result The raw result returned from MongoDB, field will vary depending on server version.
+ * @property {Number} result.ok Is 1 if the command executed correctly.
+ * @property {Number} result.n The total count of documents scanned.
+ * @property {Number} result.nModified The total count of documents modified.
+ * @property {Object} connection The connection object used for the operation.
+ * @property {Number} matchedCount The number of documents that matched the filter.
+ * @property {Number} modifiedCount The number of documents that were modified.
+ * @property {Number} upsertedCount The number of documents upserted.
+ * @property {Object} upsertedId The upserted id.
+ * @property {ObjectId} upsertedId._id The upserted _id returned from the server.
+ */
+
+/**
+ * The callback format for inserts
+ * @callback Collection~updateWriteOpCallback
+ * @param {MongoError} error An error instance representing the error during the execution.
+ * @param {Collection~updateWriteOpResult} result The result object if the command was executed successfully.
+ */
+
 /**
  * Update a single document on MongoDB
  * @method
@@ -678,7 +717,7 @@ Collection.prototype.insert = function(docs, options, callback) {
  * @param {(number|string)} [options.w=null] The write concern.
  * @param {number} [options.wtimeout=null] The write concern timeout.
  * @param {boolean} [options.j=false] Specify a journal write concern.
- * @param {Collection~writeOpCallback} [callback] The command result callback
+ * @param {Collection~updateWriteOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.updateOne = function(filter, update, options, callback) {
@@ -724,7 +763,7 @@ var updateOne = function(self, filter, update, options, callback) {
  * @param {(number|string)} [options.w=null] The write concern.
  * @param {number} [options.wtimeout=null] The write concern timeout.
  * @param {boolean} [options.j=false] Specify a journal write concern.
- * @param {Collection~writeOpCallback} [callback] The command result callback
+ * @param {Collection~updateWriteOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.replaceOne = function(filter, update, options, callback) {
@@ -771,7 +810,7 @@ var replaceOne = function(self, filter, update, options, callback) {
  * @param {(number|string)} [options.w=null] The write concern.
  * @param {number} [options.wtimeout=null] The write concern timeout.
  * @param {boolean} [options.j=false] Specify a journal write concern.
- * @param {Collection~writeOpCallback} [callback] The command result callback
+ * @param {Collection~updateWriteOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.updateMany = function(filter, update, options, callback) {
@@ -871,6 +910,22 @@ Collection.prototype.update = function(selector, document, options, callback) {
   });
 }
 
+/**
+ * @typedef {Object} Collection~deleteWriteOpResult
+ * @property {Object} result The raw result returned from MongoDB, field will vary depending on server version.
+ * @property {Number} result.ok Is 1 if the command executed correctly.
+ * @property {Number} result.n The total count of documents deleted.
+ * @property {Object} connection The connection object used for the operation.
+ * @property {Number} deletedCount The number of documents deleted.
+ */
+
+/**
+ * The callback format for inserts
+ * @callback Collection~deleteWriteOpCallback
+ * @param {MongoError} error An error instance representing the error during the execution.
+ * @param {Collection~deleteWriteOpResult} result The result object if the command was executed successfully.
+ */
+
 /**
  * Delete a document on MongoDB
  * @method
@@ -879,7 +934,7 @@ Collection.prototype.update = function(selector, document, options, callback) {
  * @param {(number|string)} [options.w=null] The write concern.
  * @param {number} [options.wtimeout=null] The write concern timeout.
  * @param {boolean} [options.j=false] Specify a journal write concern.
- * @param {Collection~writeOpCallback} [callback] The command result callback
+ * @param {Collection~deleteWriteOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.deleteOne = function(filter, options, callback) {
@@ -920,7 +975,7 @@ Collection.prototype.removeOne = Collection.prototype.deleteOne;
  * @param {(number|string)} [options.w=null] The write concern.
  * @param {number} [options.wtimeout=null] The write concern timeout.
  * @param {boolean} [options.j=false] Specify a journal write concern.
- * @param {Collection~writeOpCallback} [callback] The command result callback
+ * @param {Collection~deleteWriteOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.deleteMany = function(filter, options, callback) {
@@ -1025,6 +1080,7 @@ Collection.prototype.remove = function(selector, options, callback) {
  * @param {boolean} [options.j=false] Specify a journal write concern.
  * @param {Collection~writeOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
+ * @deprecated use insertOne, insertMany, updateOne or updateMany
  */
 Collection.prototype.save = function(doc, options, callback) {
   var self = this;
@@ -1808,6 +1864,20 @@ var stats = function(self, options, callback) {
   self.s.db.command(commandObject, options, callback);
 }
 
+/**
+ * @typedef {Object} Collection~findAndModifyWriteOpResult
+ * @property {object} value Document returned from findAndModify command.
+ * @property {object} lastErrorObject The raw lastErrorObject returned from the command.
+ * @property {Number} ok Is 1 if the command executed correctly.
+ */
+
+/**
+ * The callback format for inserts
+ * @callback Collection~findAndModifyCallback
+ * @param {MongoError} error An error instance representing the error during the execution.
+ * @param {Collection~findAndModifyWriteOpResult} result The result object if the command was executed successfully.
+ */
+
 /**
  * Find a document and delete it in one atomic operation, requires a write lock for the duration of the operation.
  *
@@ -1817,7 +1887,7 @@ var stats = function(self, options, callback) {
  * @param {object} [options.projection=null] Limits the fields to return for all matching documents.
  * @param {object} [options.sort=null] Determines which document the operation modifies if the query selects multiple documents.
  * @param {number} [options.maxTimeMS=null] The maximum amount of time to allow the query to run.
- * @param {Collection~resultCallback} [callback] The collection result callback
+ * @param {Collection~findAndModifyCallback} [callback] The collection result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.findOneAndDelete = function(filter, options, callback) {
@@ -1864,7 +1934,7 @@ var findOneAndDelete = function(self, filter, options, callback) {
  * @param {number} [options.maxTimeMS=null] The maximum amount of time to allow the query to run.
  * @param {boolean} [options.upsert=false] Upsert the document if it does not exist.
  * @param {boolean} [options.returnOriginal=true] When false, returns the updated document rather than the original. The default is true.
- * @param {Collection~resultCallback} [callback] The collection result callback
+ * @param {Collection~findAndModifyCallback} [callback] The collection result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.findOneAndReplace = function(filter, replacement, options, callback) {
@@ -1913,7 +1983,7 @@ var findOneAndReplace = function(self, filter, replacement, options, callback) {
  * @param {number} [options.maxTimeMS=null] The maximum amount of time to allow the query to run.
  * @param {boolean} [options.upsert=false] Upsert the document if it does not exist.
  * @param {boolean} [options.returnOriginal=true] When false, returns the updated document rather than the original. The default is true.
- * @param {Collection~resultCallback} [callback] The collection result callback
+ * @param {Collection~findAndModifyCallback} [callback] The collection result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Collection.prototype.findOneAndUpdate = function(filter, update, options, callback) {

lib/db.js

@@ -640,6 +640,7 @@ var evaluate = function(self, code, parameters, options, callback) {
  * @param {boolean} [options.nolock=false] Tell MongoDB not to block on the evaulation of the javascript.
  * @param {Db~resultCallback} [callback] The results callback
  * @return {Promise} returns Promise if no callback passed
+ * @deprecated MongoDB 3.2 and higher no longer support eval.
  */
 Db.prototype.eval = function(code, parameters, options, callback) {
   var self = this;
@@ -1585,47 +1586,65 @@ var createListener = function(self, e, object) {
 /**
  * Db close event
  *
+ * Emitted after a socket closed against a single server or mongos proxy.
+ *
  * @event Db#close
- * @type {object}
+ * @type {MongoError}
  */
 
 /**
  * Db authenticated event
  *
+ * Emitted after all server members in the topology (single server, replicaset or mongos) have successfully authenticated.
+ *
  * @event Db#authenticated
  * @type {object}
  */
 
 /**
  * Db reconnect event
  *
+ *  * Server: Emitted when the driver has reconnected and re-authenticated.
+ *  * ReplicaSet: N/A
+ *  * Mongos: Emitted when the driver reconnects and re-authenticates successfully against a Mongos.
+ *
  * @event Db#reconnect
  * @type {object}
  */
 
 /**
  * Db error event
  *
+ * Emitted after an error occurred against a single server or mongos proxy.
+ *
  * @event Db#error
  * @type {MongoError}
  */
 
 /**
  * Db timeout event
  *
+ * Emitted after a socket timeout occurred against a single server or mongos proxy.
+ *
  * @event Db#timeout
- * @type {object}
+ * @type {MongoError}
  */
 
 /**
  * Db parseError event
  *
+ * The parseError event is emitted if the driver detects illegal or corrupt BSON being received from the server.
+ *
  * @event Db#parseError
- * @type {object}
+ * @type {MongoError}
  */
 
 /**
- * Db fullsetup event, emitted when all servers in the topology have been connected to.
+ * Db fullsetup event, emitted when all servers in the topology have been connected to at start up time.
+ *
+ * * Server: Emitted when the driver has connected to the single server and has authenticated.
+ * * ReplSet: Emitted after the driver has attempted to connect to all replicaset members.
+ * * Mongos: Emitted after the driver has attempted to connect to all mongos proxies.
  *
  * @event Db#fullsetup
  * @type {Db}

test/functional/crud_api_tests.js

@@ -708,6 +708,8 @@ exports['should correctly execute findAndModify methods using crud api'] = {
           db.collection('t5_1').findOneAndDelete({a:1}
             , { projection: {b:1}, sort: {a:1} }
             , function(err, r) {
+              console.log("------------------------------------------------ findOneAndDelete")
+              console.dir(r)
               test.equal(null, err);
               test.equal(1, r.lastErrorObject.n);
               test.equal(1, r.value.b);
@@ -734,6 +736,8 @@ exports['should correctly execute findAndModify methods using crud api'] = {
                 , upsert: true
               }
             , function(err, r) {
+              console.log("------------------------------------------------ findOneAndReplace")
+              console.dir(r)
               test.equal(null, err);
               test.equal(1, r.lastErrorObject.n);
               test.equal(1, r.value.b);
@@ -761,6 +765,8 @@ exports['should correctly execute findAndModify methods using crud api'] = {
                 , upsert: true
               }
             , function(err, r) {
+              console.log("------------------------------------------------ findOneAndUpdate")
+              console.dir(r)
               test.equal(null, err);
               test.equal(1, r.lastErrorObject.n);
               test.equal(1, r.value.b);