docs(query): add more detailed docs re: options

Fix #1702
Automattic · Nov 23, 2017 · fe0d1c5 · fe0d1c5
1 parent dc19eac
commit fe0d1c5
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 27 deletions.
diff --git a/lib/model.js b/lib/model.js
@@ -1326,7 +1326,7 @@ Model.deleteMany = function deleteMany(conditions, callback) {
  *
  * @param {Object} conditions
  * @param {Object} [projection] optional fields to return (http://bit.ly/1HotzBo)
- * @param {Object} [options] optional
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @see field selection #query_Query-select
@@ -1406,7 +1406,7 @@ Model.find = function find(conditions, projection, options, callback) {
  *
  * @param {Object|String|Number} id value of `_id` to query by
  * @param {Object} [projection] optional fields to return (http://bit.ly/1HotzBo)
- * @param {Object} [options] optional
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @see field selection #query_Query-select
@@ -1460,7 +1460,7 @@ Model.findById = function findById(id, projection, options, callback) {
  *
  * @param {Object} [conditions]
  * @param {Object} [projection] optional fields to return (http://bit.ly/1HotzBo)
- * @param {Object} [options] optional
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @see field selection #query_Query-select
@@ -1685,7 +1685,7 @@ Model.$where = function $where() {
  *
  * @param {Object} [conditions]
  * @param {Object} [update]
- * @param {Object} [options]
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @see mongodb http://www.mongodb.org/display/DOCS/findAndModify+Command
@@ -1804,7 +1804,7 @@ Model.findOneAndUpdate = function(conditions, update, options, callback) {
  *
  * @param {Object|Number|String} id value of `_id` to query by
  * @param {Object} [update]
- * @param {Object} [options]
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @see Model.findOneAndUpdate #model_Model.findOneAndUpdate
@@ -1881,7 +1881,7 @@ Model.findByIdAndUpdate = function(id, update, options, callback) {
  *     });
  *
  * @param {Object} conditions
- * @param {Object} [options]
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @see mongodb http://www.mongodb.org/display/DOCS/findAndModify+Command
@@ -1943,7 +1943,7 @@ Model.findOneAndRemove = function(conditions, options, callback) {
  *     A.findByIdAndRemove()           // returns Query
  *
  * @param {Object|Number|String} id value of `_id` to query by
- * @param {Object} [options]
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @see Model.findOneAndRemove #model_Model.findOneAndRemove
@@ -2507,7 +2507,7 @@ Model.hydrate = function(obj) {
  * @see response http://docs.mongodb.org/v2.6/reference/command/update/#output
  * @param {Object} conditions
  * @param {Object} doc
- * @param {Object} [options]
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @api public
@@ -2530,7 +2530,7 @@ Model.update = function update(conditions, doc, options, callback) {
  *
  * @param {Object} conditions
  * @param {Object} doc
- * @param {Object} [options]
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @api public
@@ -2549,7 +2549,7 @@ Model.updateMany = function updateMany(conditions, doc, options, callback) {
  *
  * @param {Object} conditions
  * @param {Object} doc
- * @param {Object} [options]
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @api public
@@ -2568,7 +2568,7 @@ Model.updateOne = function updateOne(conditions, doc, options, callback) {
  *
  * @param {Object} conditions
  * @param {Object} doc
- * @param {Object} [options]
+ * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
  * @api public

diff --git a/lib/query.js b/lib/query.js
@@ -952,25 +952,31 @@ Query.prototype.read = function read(pref, tags) {
  */
 
 /**
- * Sets query options.
+ * Sets query options. Some options only make sense for certain operations.
  *
  * ####Options:
  *
- * - [tailable](http://www.mongodb.org/display/DOCS/Tailable+Cursors) *
- * - [sort](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bsort(\)%7D%7D) *
- * - [limit](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Blimit%28%29%7D%7D) *
- * - [skip](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bskip%28%29%7D%7D) *
- * - [maxscan](https://docs.mongodb.org/v3.2/reference/operator/meta/maxScan/#metaOp._S_maxScan) *
- * - [batchSize](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7BbatchSize%28%29%7D%7D) *
- * - [comment](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%24comment) *
- * - [snapshot](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bsnapshot%28%29%7D%7D) *
- * - [hint](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%24hint) *
- * - [readPreference](http://docs.mongodb.org/manual/applications/replication/#read-preference) **
- * - [lean](./api.html#query_Query-lean) *
- * - [safe](http://www.mongodb.org/display/DOCS/getLastError+Command)
- *
- * _* denotes a query helper method is also available_
- * _** query helper method to set `readPreference` is `read()`_
+ * The following options are only for `find()`:
+ * - [tailable](http://www.mongodb.org/display/DOCS/Tailable+Cursors)
+ * - [sort](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bsort(\)%7D%7D)
+ * - [limit](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Blimit%28%29%7D%7D)
+ * - [skip](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bskip%28%29%7D%7D)
+ * - [maxscan](https://docs.mongodb.org/v3.2/reference/operator/meta/maxScan/#metaOp._S_maxScan)
+ * - [batchSize](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7BbatchSize%28%29%7D%7D)
+ * - [comment](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%24comment)
+ * - [snapshot](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bsnapshot%28%29%7D%7D)
+ * - [readPreference](http://docs.mongodb.org/manual/applications/replication/#read-preference)
+ * - [hint](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%24hint)
+ *
+ * The following options are only for `update()`, `updateOne()`, `updateMany()`, `replaceOne()`, and `findOneAndUpdate()`:
+ * - [upsert](https://docs.mongodb.com/manual/reference/method/db.collection.update/)
+ * - [writeConcern](https://docs.mongodb.com/manual/reference/method/db.collection.update/)
+ *
+ * The following options are only for `find()`, `findOne()`, `findById()`, and `findOneAndUpdate()`:
+ * - [lean](./api.html#query_Query-lean)
+ *
+ * The following options are for all operations:
+ * - [collation](https://docs.mongodb.com/manual/reference/collation/)
  *
  * @param {Object} options
  * @api public
@@ -1522,6 +1528,7 @@ Query.prototype._findOne = function(callback) {
  *
  * @param {Object|Query} [criteria] mongodb selector
  * @param {Object} [projection] optional fields to return
+ * @param {Object} [options] see [`setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback] optional params are (error, document)
  * @return {Query} this
  * @see findOne http://docs.mongodb.org/manual/reference/method/db.collection.findOne/