From bd2541b92b8e0a072fa0bc2813d4507dc1d32fc8 Mon Sep 17 00:00:00 2001
From: Will Bailey <wbailey@fb.com>
Date: Sun, 3 Aug 2014 09:22:03 -0700
Subject: [PATCH] add some comments

---
 examples/example.js         | 10 ++++----
 examples/hamburgerButton.js | 49 ++++++++++++++++++++++++++++++-------
 examples/index.html         |  5 ++--
 3 files changed, 47 insertions(+), 17 deletions(-)

diff --git a/examples/example.js b/examples/example.js
index e1ed08f..b50b859 100644
--- a/examples/example.js
+++ b/examples/example.js
@@ -7,12 +7,12 @@ createHamburgerButtonExample = function(container, size, color, bgColor) {
 };
 
 var doit = function() {
-  var container = document.getElementById('hamburgerButton');
+  var container = document.getElementById('hamburgerButtonExample');
   createHamburgerButtonExample(container, 200, '#999');
-  createHamburgerButtonExample(container, 200, '#FFFFFF', '#000');
-  createHamburgerButtonExample(container, 100, '#FF0000');
-  createHamburgerButtonExample(container, 50, '#00FF00');
-  createHamburgerButtonExample(container, 25, '#0000FF');
+  createHamburgerButtonExample(container, 200, '#FFFFFF', '#999');
+  createHamburgerButtonExample(container, 200, '#FF0000');
+  createHamburgerButtonExample(container, 50, '#000');
+  createHamburgerButtonExample(container, 25, '#000');
 };
 
 document.addEventListener('DOMContentLoaded', doit);
\ No newline at end of file
diff --git a/examples/hamburgerButton.js b/examples/hamburgerButton.js
index 30807ce..d846efb 100644
--- a/examples/hamburgerButton.js
+++ b/examples/hamburgerButton.js
@@ -1,38 +1,53 @@
 (function() {
   var hb = {};
 
+  // import a couple of utils from rebound.
   var deg2rad = rebound.MathUtil.degreesToRadians;
   var mapVal = rebound.MathUtil.mapValueInRange;
 
-  hb.HamburgerButton = function(container, size, color, cornerRadius) {
+  // HamburgerButton animates between a 3 bar menu icon and an X icon using a
+  // Rebound spring to drive the animation. You can configure its container, size
+  // and color.
+  hb.HamburgerButton = function(container, size, color) {
     this.canvas = document.createElement('canvas');
     this.ctx = this.canvas.getContext('2d');
+
+    // Configure all the styles and dimensions for the button.
     this.padding = size * 0.1;
     this.size = size - this.padding * 2;
     this.width = this.size;
     this.height = this.size;
     this.canvas.width = size;
     this.canvas.height = size;
-    this.barHeight = this.size / 5;
+    this.barHeight = this.size / 6;
     this.rotatedXlat = Math.sqrt((this.barHeight * this.barHeight) / 2);
-    this.radius = cornerRadius || this .size * 0.05;
+    this.radius = this .size * 0.05;
     var ab = (this.width - this.rotatedXlat);
     this.rotatedWidth = Math.sqrt(ab * ab + ab * ab);
     this.color = color;
 
+    // Clear out the target container.
     this.container = container;
     this.container.innerHTML = '';
 
+    // Create our animation spring. Here you could also pass in a custom SpringConfig
+    // if you wanted to get a more or less bouncy animation curve.
     this.springSystem = new rebound.SpringSystem();
     this.animationSpring = this.springSystem.createSpring();
     this.animationSpring.addListener(this);
 
+    // Perform and initial render to the canvas and apend the example canvas to
+    // the container.
     this.render();
     container.appendChild(this.canvas);
     this.canvas.addEventListener('click', bind(this.toggle, this));
   };
 
   extend(hb.HamburgerButton.prototype, {
+    /**
+     * Switch the spring between its open (0) and closed (1) states. This will
+     * drive the spring to animate, which will trigger rendering of the component.
+     */
     toggle: function() {
       if (this.animationSpring.getEndValue() === 1) {
         this.animationSpring.setEndValue(0);
@@ -41,10 +56,16 @@
       }
     },
 
+    /**
+     * Listen to the spring and call render whenever it updates.
+     */
     onSpringUpdate: function(spring) {
       this.render();
     },
 
+    /**
+     * This just draws a rounded rect with the configured corner radius and dimensions.
+     */
     drawBar: function(width) {
       this.ctx.fillStyle = this.color;
 
@@ -63,6 +84,14 @@
       this.ctx.fill();
     },
 
+    /**
+     * On every frame of the animation, render will draw the current state of
+     * the animation based on interpolation of the springs value between 0 and 1.
+     * Driving an animation off of a zero to one spring is a really simple way
+     * to coordinate multiple transitions on a common animation spring.
+     * `rebound.MathUtil.mapValueInRange` is helpful for converting numbers between
+     * an input range and an output range.
+     */
     render: function() {
       this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
 
@@ -110,12 +139,7 @@
     }
   });
 
-  // Utils
-  if (typeof exports != 'undefined') {
-    extend(exports, hb);
-  } else if (typeof window != 'undefined') {
-    window.hamburgerButton = hb;
-  }
+  // Create a couple of utilities.
 
   var slice = Array.prototype.slice;
   var concat = Array.prototype.concat;
@@ -134,4 +158,11 @@
       }
     }
   }
+
+  // Export the control.
+  if (typeof exports != 'undefined') {
+    extend(exports, hb);
+  } else if (typeof window != 'undefined') {
+    window.hamburgerButton = hb;
+  }
 })();
\ No newline at end of file
diff --git a/examples/index.html b/examples/index.html
index 83e8763..f4e3b63 100644
--- a/examples/index.html
+++ b/examples/index.html
@@ -16,11 +16,10 @@ <h2 class="exampleTitle">Hamburger Button Example</h2>
     Paper for transitioning a hamburger button into a close button. The animation
     timing is run on a Rebound spring and each frame of the animation is interpolated
     from a zero to one spring transition and drawn in canvas. Tap/Click on buttons
-    to transition between the states.
+    to transition between the states. (<a href="https://github.com/facebook/rebound-js/blob/master/examples/hamburgerButton.js" target="_blank">Code</a>)
   </div>
-  <div id="hamburgerButton" class="exampleContainer">
+  <div id="hamburgerButtonExample" class="exampleContainer">
   </div>
-  <script src="http://gist-it.appspot.com/github/facebook/rebound-js/blob/master/examples/hamburgerButton.js"></script>
 </div>
 
 </body>