docs(virtualtype+populate): document using match with virtual populate

Fix #8616

docs/populate.pug

@@ -576,6 +576,36 @@ block content
     });
     ```
 
+    You can also use [the populate `match` option](http://thecodebarbarian.com/mongoose-5-5-static-hooks-and-populate-match-functions.html#populate-match-function)
+    to add an additional filter to the `populate()` query. This is useful
+    if you need to split up `populate()` data:
+
+    ```javascript
+    const PersonSchema = new Schema({
+      name: String,
+      band: String,
+      isActive: Boolean
+    });
+
+    const BandSchema = new Schema({
+      name: String
+    });
+    BandSchema.virtual('activeMembers', {
+      ref: 'Person',
+      localField: 'name',
+      foreignField: 'band',
+      justOne: false,
+      match: { isActive: true }
+    });
+    BandSchema.virtual('formerMembers', {
+      ref: 'Person',
+      localField: 'name',
+      foreignField: 'band',
+      justOne: false,
+      match: { isActive: false }
+    });
+    ```
+
     Keep in mind that virtuals are _not_ included in `toJSON()` output by default. If you want populate virtuals to show up when using functions
     that rely on `JSON.stringify()`, like Express'
     [`res.json()` function](http://expressjs.com/en/4x/api.html#res.json),

lib/virtualtype.js

@@ -17,6 +17,11 @@
  * @param {boolean} [options.justOne=false] by default, a populated virtual is an array. If you set `justOne`, the populated virtual will be a single doc or `null`.
  * @param {boolean} [options.getters=false] if you set this to `true`, Mongoose will call any custom getters you defined on this virtual
  * @param {boolean} [options.count=false] if you set this to `true`, `populate()` will set this virtual to the number of populated documents, as opposed to the documents themselves, using [`Query#countDocuments()`](./api.html#query_Query-countDocuments)
+ * @param {Object|Function} [options.match=null] add an extra match condition to `populate()`
+ * @param {Number} [options.limit=null] add a default `limit` to the `populate()` query
+ * @param {Number} [options.skip=null] add a default `skip` to the `populate()` query
+ * @param {Number} [options.perDocumentLimit=null] For legacy reasons, `limit` with `populate()` may give incorrect results because it only executes a single query for every document being populated. If you set `perDocumentLimit`, Mongoose will ensure correct `limit` per document by executing a separate query for each document to `populate()`. For example, `.find().populate({ path: 'test', perDocumentLimit: 2 })` will execute 2 additional queries if `.find()` returns 2 documents.
+ * @param {Object} [options.options=null] Additional options like `limit` and `lean`.
  * @api public
  */