From 5140e62fd32cb169d2a3979c130f571c55d649ac Mon Sep 17 00:00:00 2001
From: Valeri Karpov <valkar207@gmail.com>
Date: Fri, 20 Jan 2017 19:28:37 -0700
Subject: [PATCH] docs: explain selecting foreignField in populate virtuals

Re: #4923
---
 docs/populate.jade | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/populate.jade b/docs/populate.jade
index cf4f1dd9428..bd78b74c23f 100644
--- a/docs/populate.jade
+++ b/docs/populate.jade
@@ -357,6 +357,25 @@ block content
     var BandSchema = new Schema({
       name: String
     }, { toJSON: { virtuals: true } });
+  
+  :markdown
+    If you're using populate projections, make sure `foreignField` is included
+    in the projection.
+    
+  :js
+    Band.
+      find({}).
+      populate({ path: 'members', select: 'name' }).
+      exec(function(error, bands) {
+        // Won't work, foreign field `band` is not selected in the projection
+      });
+
+    Band.
+      find({}).
+      populate({ path: 'members', select: 'name band' }).
+      exec(function(error, bands) {
+        // Works, foreign field `band` is selected
+      });
 
   h3#next Next Up
   :markdown