docs(model+query): document using array of strings as projection

Fix #9413

lib/model.js

@@ -2009,7 +2009,7 @@ Model.deleteMany = function deleteMany(conditions, options, callback) {
  *     await MyModel.find({ name: /john/i }, null, { skip: 10 }).exec();
  *
  * @param {Object|ObjectId} filter
- * @param {Object|String} [projection] optional fields to return, see [`Query.prototype.select()`](http://mongoosejs.com/docs/api.html#query_Query-select)
+ * @param {Object|String|Array<String>} [projection] optional fields to return, see [`Query.prototype.select()`](http://mongoosejs.com/docs/api.html#query_Query-select)
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
@@ -2079,7 +2079,7 @@ Model.find = function find(conditions, projection, options, callback) {
  *     await Adventure.findById(id, 'name length').exec();
  *
  * @param {Any} id value of `_id` to query by
- * @param {Object|String} [projection] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
+ * @param {Object|String|Array<String>} [projection] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
@@ -2122,7 +2122,7 @@ Model.findById = function findById(id, projection, options, callback) {
  *     await Adventure.findOne({ country: 'Croatia' }, 'name length').exec();
  *
  * @param {Object} [conditions]
- * @param {Object|String} [projection] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
+ * @param {Object|String|Array<String>} [projection] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Function} [callback]
  * @return {Query}
@@ -2431,6 +2431,7 @@ Model.$where = function $where() {
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
  * @param {Boolean} [options.returnOriginal=null] An alias for the `new` option. `returnOriginal: false` is equivalent to `new: true`.
  * @param {Boolean} [options.overwrite=false] By default, if you don't include any [update operators](https://docs.mongodb.com/manual/reference/operator/update/) in `update`, Mongoose will wrap `update` in `$set` for you. This prevents you from accidentally overwriting the document. This option tells Mongoose to skip adding `$set`. An alternative to this would be using [Model.findOneAndReplace(conditions, update, options, callback)](https://mongoosejs.com/docs/api/model.html#model_Model.findOneAndReplace).
+ * @param {Object|String|Array<String>} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {Function} [callback]
  * @return {Query}
  * @see Tutorial /docs/tutorials/findoneandupdate.html
@@ -2626,8 +2627,8 @@ Model.findByIdAndUpdate = function(id, update, options, callback) {
  *
  * - `sort`: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
  * - `maxTimeMS`: puts a time limit on the query - requires mongodb >= 2.6.0
- * - `select`: sets the document fields to return
- * - `projection`: like select, it determines which fields to return, ex. `{ projection: { _id: 0 } }`
+ * - `select`: sets the document fields to return, ex. `{ projection: { _id: 0 } }`
+ * - `projection`: equivalent to `select`
  * - `rawResult`: if true, returns the [raw result from the MongoDB driver](http://mongodb.github.io/node-mongodb-native/2.0/api/Collection.html#findAndModify)
  * - `strict`: overwrites the schema's [strict mode option](http://mongoosejs.com/docs/guide.html#strict) for this update
  *
@@ -2660,6 +2661,7 @@ Model.findByIdAndUpdate = function(id, update, options, callback) {
  * @param {Object} conditions
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](http://mongoosejs.com/docs/guide.html#strict)
+ * @param {Object|String|Array<String>} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](/docs/transactions.html).
  * @param {Function} [callback]
  * @return {Query}
@@ -2772,6 +2774,7 @@ Model.findByIdAndDelete = function(id, options, callback) {
  * @param {Boolean} [options.omitUndefined=false] If true, delete any properties whose value is `undefined` when casting an update. In other words, if this is set, Mongoose will delete `baz` from the update in `Model.updateOne({}, { foo: 'bar', baz: undefined })` before sending the update to the server.
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
  * @param {Boolean} [options.returnOriginal=null] An alias for the `new` option. `returnOriginal: false` is equivalent to `new: true`.
+ * @param {Object|String|Array<String>} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {Function} [callback]
  * @return {Query}
  * @api public
@@ -2862,6 +2865,7 @@ Model.findOneAndReplace = function(filter, replacement, options, callback) {
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](/docs/transactions.html).
  * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](http://mongoosejs.com/docs/guide.html#strict)
+ * @param {Object|String|Array<String>} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {Function} [callback]
  * @return {Query}
  * @see mongodb http://www.mongodb.org/display/DOCS/findAndModify+Command
@@ -2927,6 +2931,7 @@ Model.findOneAndRemove = function(conditions, options, callback) {
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](http://mongoosejs.com/docs/api.html#query_Query-setOptions)
  * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](http://mongoosejs.com/docs/guide.html#strict)
  * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](/docs/transactions.html).
+ * @param {Object|String|Array<String>} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {Function} [callback]
  * @return {Query}
  * @see Model.findOneAndRemove #model_Model.findOneAndRemove
@@ -3497,7 +3502,7 @@ Model.bulkWrite = function(ops, options, callback) {
  *     const mongooseCandy = Candy.hydrate({ _id: '54108337212ffb6d459f854c', type: 'jelly bean' });
  *
  * @param {Object} obj
- * @param {Object|String} [projection] optional projection containing which fields should be selected for this document
+ * @param {Object|String|Array<String>} [projection] optional projection containing which fields should be selected for this document
  * @return {Document} document instance
  * @api public
  */

lib/query.js

@@ -910,6 +910,9 @@ Query.prototype.projection = function(arg) {
  *
  *     // include a and b, exclude other fields
  *     query.select('a b');
+ *     // Equivalent syntaxes:
+ *     query.select(['a', 'b']);
+ *     query.select({ a: 1, b: 1 });
  *
  *     // exclude c and d, include other fields
  *     query.select('-c -d');
@@ -932,7 +935,7 @@ Query.prototype.projection = function(arg) {
  * @method select
  * @memberOf Query
  * @instance
- * @param {Object|String} arg
+ * @param {Object|String|Array<String>} arg
  * @return {Query} this
  * @see SchemaType
  * @api public