document the HTML matching algorithm better

1 files changed, 14 insertions, 4 deletions

diff --git a/lib/completion.js b/lib/completion.js
index 6e8ea803..0b4c5a0a 100644
--- a/lib/completion.js
+++ b/lib/completion.js
@@ -139,15 +139,20 @@ var completion = (function() {
   /** Creates a completion that renders by marking fuzzy-matched parts. */
   function createHighlightingCompletion(query, str, action, relevancy) {
     return {
+      action: action,
+      relevancy: relevancy,
+
       render: function() {
+        // we want to match the content in HTML tags, but not the HTML tags themselves, so we remove the
+        // tags and reinsert them after the matching process
         var htmlTags = {};
         str = stripHtmlTags(str, htmlTags);
         var match = fuzzyMatcher.getMatcher(query).exec(str);
-        if (!match)
-          console.log(query, str);
         var html = '';
         var i = 0;
 
+        // this helper function adds the HTML generated _for one single character_ to the HTML output
+        // and reinserts HTML tags stripped before, if they were at this position
         function addToHtml(str) {
           if (i in htmlTags)
             html += htmlTags[i];
@@ -155,19 +160,24 @@ var completion = (function() {
           ++i;
         }
 
+        // iterate over the match groups. They are non-matched and matched string parts, in alternating order
         for (var m = 1; m < match.length; ++m) {
           if (m % 2 == 1)
+            // we have a non-matched part, it could have several characters. We need to insert them character
+            // by character, so that addToHtml can keep track of the position in the original string
             for (var j = 0; j < match[m].length; ++j)
               addToHtml(match[m][j]);
           else
+            // we have a matched part, which consists of exactly one character. In addition to the character
+            // itself, we add some decorating HTML.
             addToHtml('<span class="fuzzyMatch">' + match[m] + '</span>');
         };
+
+        // call it another time so that a tag at the very last position is reinserted
         addToHtml('');
 
         return html;
       },
-      action: action,
-      relevancy: relevancy,
     }
   }