From 143294ab9d8e564a47a4374663b51e1f6f414c03 Mon Sep 17 00:00:00 2001
From: Michael Halle <m -@- halle.us>
Date: Mon, 11 Apr 2016 10:14:02 -0400
Subject: [PATCH] Improved comments for changes to fieldSearch.

---
 lib/index.js | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/lib/index.js b/lib/index.js
index f0826ae5..83c99312 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -387,6 +387,24 @@ elasticlunr.Index.prototype.fieldSearch = function (queryTokens, fieldName, conf
     if (expand == true) {
       tokens = this.index[fieldName].expandToken(token);
     }
+    // Consider every query token in turn. If expanded, each query token
+    // corresponds to a set of tokens, which is all tokens in the 
+    // index matching the pattern queryToken* .
+    // For the set of tokens corresponding to a query token, find and score
+    // all matching documents. Store those scores in queryTokenScores, 
+    // keyed by docRef.
+    // Then, depending on the value of booleanType, combine the scores
+    // for this query token with previous scores.  If booleanType is OR,
+    // then merge the scores by summing into the accumulated total, adding
+    // new document scores are required (effectively a union operator). 
+    // If booleanType is AND, accumulate scores only if the document 
+    // has previously been scored by another query token (an intersection
+    // operation0. 
+    // Furthermore, since when booleanType is AND, additional 
+    // query tokens can't add new documents to the result set, use the
+    // current document set to limit the processing of each new query 
+    // token for efficiency (i.e., incremental intersection).
+    
     var queryTokenScores = {};
     tokens.forEach(function (key) {
       var docs = this.index[fieldName].getDocs(key);
@@ -394,8 +412,8 @@ elasticlunr.Index.prototype.fieldSearch = function (queryTokens, fieldName, conf
       
       if (scores && booleanType == 'AND') {
           // special case, we can rule out documents that have been
-          // already been filtered out because they don't contain 
-          // required tokens.
+          // already been filtered out because they weren't scored
+          // by previous query token passes.
           var filteredDocs = {};
           for (var docRef in scores) {
               if (docRef in docs) {
@@ -404,7 +422,6 @@ elasticlunr.Index.prototype.fieldSearch = function (queryTokens, fieldName, conf
           }
           docs = filteredDocs;
       }
-
       // only record appeared token for retrieved documents for the
       // original token, not for expaned token.
       // beause for doing coordNorm for a retrieved document, coordNorm only care how many