From ce41796f8b1f03c8501cad263c1f3170a7a8dd94 Mon Sep 17 00:00:00 2001
From: Jeff Avallone <jeff.avallone@gmail.com>
Date: Sun, 19 Apr 2015 21:16:54 -0400
Subject: [PATCH] Adding documentation to match_fragment.js

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

diff --git a/src/js/parser/javascript/match_fragment.js b/src/js/parser/javascript/match_fragment.js
index 0c1730b..e200613 100644
--- a/src/js/parser/javascript/match_fragment.js
+++ b/src/js/parser/javascript/match_fragment.js
@@ -1,9 +1,16 @@
+// MatchFragment nodes are part of a [Match](./match.html) followed by an
+// optional [Repeat](./repeat.html) node. If no repeat is applied, then
+// rendering is proxied to the content node.
+
 import _ from 'lodash';
 
 export default {
   type: 'match-fragment',
 
   definedProperties: {
+    // Default anchor is overridden to apply an transforms from the fragment
+    // to its content's anchor. Essentially, the fragment inherits the anchor
+    // of its content.
     _anchor: {
       get: function() {
         var anchor = this.content.getBBox(),
@@ -18,15 +25,18 @@ export default {
     }
   },
 
+  // Renders the fragment into the currently set container.
   _render() {
     return this.content.render(this.container.group())
       .then(() => {
         var box, paths;
 
+        // Contents must be transformed based on the repeat that is applied.
         this.content.transform(this.repeat.contentPosition);
 
         box = this.content.getBBox();
 
+        // Add skip or repeat paths to the container.
         paths = _.flatten([
           this.skipPath(box),
           this.loopPath(box)
@@ -39,6 +49,8 @@ export default {
       });
   },
 
+  // Returns the path spec to render the line that skips over the content for
+  // fragments that are optionally matched.
   skipPath(box) {
     var paths = [];
 
@@ -48,6 +60,7 @@ export default {
 
       paths.push(`M0,${box.ay}q10,0 10,-10v${-vert}q0,-10 10,-10h${horiz}q10,0 10,10v${vert}q0,10 10,10`);
 
+      // When the repeat is not greedy, the skip path gets a preference arrow.
       if (!this.repeat.greedy) {
         paths.push(`M10,${box.ay - 15}l5,5m-5,-5l-5,5`);
       }
@@ -56,6 +69,8 @@ export default {
     return paths;
   },
 
+  // Returns the path spec to render the line that repeats the content for
+  // fragments that are matched more than once.
   loopPath(box) {
     var paths = [];
 
@@ -64,6 +79,7 @@ export default {
 
       paths.push(`M${box.x},${box.ay}q-10,0 -10,10v${vert}q0,10 10,10h${box.width}q10,0 10,-10v${-vert}q0,-10 -10,-10`);
 
+      // When the repeat is greedy, the loop path gets the preference arrow.
       if (this.repeat.greedy) {
         paths.push(`M${box.x2 + 10},${box.ay + 15}l5,-5m-5,5l-5,-5`);
       }
@@ -72,6 +88,8 @@ export default {
     return paths;
   },
 
+  // Renders label for the loop path indicating how many times the content may
+  // be matched.
   loopLabel() {
     var labelStr = this.repeat.label,
         label, labelBox, box;
@@ -89,13 +107,19 @@ export default {
   },
 
   setup() {
+    // Then content of the fragment.
     this.content = this.properties.content;
+    // The repetition rule for the fragment.
     this.repeat = this.properties.repeat;
 
     if (!this.repeat.hasLoop && !this.repeat.hasSkip) {
+      // For fragments without a skip or loop, rendering is proxied to the
+      // content. Also set flag indicating that contents can be merged if the
+      // content is a literal node.
       this.canMerge = (this.content.type === 'literal');
       this.proxy = this.content;
     } else {
+      // Fragments that have skip or loop lines cannot be merged with others.
       this.canMerge = false;
     }
   }