(#1264 pouchdb/mapreduce#37) - document eval avoidance

docs/api.md

@@ -541,6 +541,35 @@ db.query({map: map}, {reduce: false}, function(err, response) { });
 }
 {% endhighlight %}
 
+If you pass a function to `db.query` and give it the `emit` function as the second argument, then you can use a closure. (Otherwise we have to use `eval()` to bind `emit`.)
+
+{% highlight js %}
+// BAD! will throw error
+var myId = 'foo';
+db.query(function(doc) {
+  if (doc._id === myId) {
+    emit(doc);
+  }
+}, function(err, results) { /* ... */ });
+
+// will be fine
+var myId = 'foo';
+db.query(function(doc, emit) {
+  if (doc._id === myId) {
+    emit(doc);
+  }
+}, function(err, results) { /* ... */ });
+{% endhighlight %}
+
+You don't actuallly have to call them by those names, though:
+{% highlight js %}
+var myId = 'foo';
+db.query(function(thisIs, awesome) {
+  if (thisIs._id === myId) {
+    awesome(thisIs); 
+  }
+}, function(err, results) { /* ... */ });
+{% endhighlight %}
 **Notes:**
 
 1. Local databases do not currently support view caching; everything is a live view.