From 1b036634730599d04bd3fcfcda5378f1207f0ddd Mon Sep 17 00:00:00 2001
From: Jeff Avallone <jeff.avallone@gmail.com>
Date: Tue, 21 Apr 2015 20:23:55 -0400
Subject: [PATCH] Adding documentation to match.js

---
 src/js/parser/javascript/match.js | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/src/js/parser/javascript/match.js b/src/js/parser/javascript/match.js
index bcb741d..4ed45b4 100644
--- a/src/js/parser/javascript/match.js
+++ b/src/js/parser/javascript/match.js
@@ -1,3 +1,8 @@
+// Match nodes are used for the parts of a regular expression between `|`
+// symbols. They consist of a series of [MatchFragment](./match_fragment.html)
+// nodes. Optional `^` and `$` symbols are also allowed at the beginning and
+// end of the Match.
+
 import util from '../../util.js';
 import _ from 'lodash';
 
@@ -5,6 +10,8 @@ export default {
   type: 'match',
 
   definedProperties: {
+    // Default anchor is overridden to attach the left point of the anchor to
+    // the first element, and the right point to the last element.
     _anchor: {
       get: function() {
         var start = util.normalizeBBox(this.start.getBBox()),
@@ -20,11 +27,14 @@ export default {
     }
   },
 
+  // Renders the match into the currently set container.
   _render() {
     var start, end,
         partPromises,
         items;
 
+    // A `^` at the beginning of the match leads to the "Start of line"
+    // indicator being rendered.
     if (this.anchorStart) {
       start = this.renderLabel('Start of line')
         .then(label => {
@@ -32,6 +42,8 @@ export default {
         });
     }
 
+    // A `$` at the end of the match leads to the "End of line" indicator
+    // being rendered.
     if (this.anchorEnd) {
       end = this.renderLabel('End of line')
         .then(label => {
@@ -39,18 +51,24 @@ export default {
         });
     }
 
+    // Render each of the match fragments.
     partPromises = _.map(this.parts, part => {
       return part.render(this.container.group());
     });
 
     items = _([start, partPromises, end]).flatten().compact().value();
 
+    // Handle the situation where a regular expression of `()` is rendered.
+    // This leads to a Match node with no fragments, no start indicator, and
+    // no end indicator. Something must be rendered so that the anchor can be
+    // calculated based on it.
     if (items.length === 0) {
       items = [this.container.group()];
     }
 
     return Promise.all(items)
       .then(items => {
+        // Find SVG elements to be used when calculating the anchor.
         this.start = _.first(items);
         this.end = _.last(items);
 
@@ -58,11 +76,14 @@ export default {
           padding: 10
         });
 
+        // Add lines between each item.
         this.container.prepend(
           this.container.path(this.connectorPaths(items).join('')));
       });
   },
 
+  // Returns an array of SVG path strings between each item.
+  // - __items__ - Array of SVG elements or nodes.
   connectorPaths(items) {
     var prev, next;
 
@@ -79,21 +100,29 @@ export default {
   },
 
   setup() {
+    // Merged list of MatchFragments to be rendered.
     this.parts = _.reduce(this.properties.parts.elements, function(result, node) {
       var last = _.last(result);
 
       if (last && node.canMerge && last.canMerge) {
+        // Merged the content of `node` into `last` when possible. This also
+        // discards `node` in the process since `result` has not been changed.
         last.content.merge(node.content);
       } else {
+        // `node` cannot be merged with the previous node, so it is added to
+        // the list of parts.
         result.push(node);
       }
 
       return result;
     }, []);
 
+    // Indicates if the expression starts with a `^`.
     this.anchorStart = (this.properties.anchor_start.textValue !== '');
+    // Indicates if the expression ends with a `$`.
     this.anchorEnd = (this.properties.anchor_end.textValue !== '');
 
+    // When there are no anchors and only one part, then proxy to the part.
     if (!this.anchorStart && !this.anchorEnd && this.parts.length === 1) {
       this.proxy = this.parts[0];
     }