More code cleanup and review tags. Part of code review, see #29.

js/neuron/NeuronScreen.js

@@ -1,7 +1,8 @@
 //  Copyright 2002-2014, University of Colorado Boulder
 
 /**
- * The 'Neuron' screen, which shows everything in that screen.
+ * The main screen class for the 'Neuron' simulation.  This is where the main model and view instances are created and
+ * inserted into the framework.
  *
  * @author Sam Reid (PhET Interactive Simulations)
  */
@@ -25,8 +26,8 @@ define( function( require ) {
    */
   function NeuronScreen() {
     var neuronModel = new NeuronModel();
-    // NeuronModelAdapter intercepts the default Step function and provides
-    // "constant" clock and record Playback features to NeuronModel, see NeuronClockModelAdapter
+    // NeuronModelAdapter intercepts the default Step function and provides "constant" clock and record Playback
+    // features to NeuronModel, see NeuronClockModelAdapter
     var neuronClockModelAdapter = new NeuronClockModelAdapter( neuronModel, NeuronConstants.CLOCK_FRAME_RATE,
       NeuronConstants.DEFAULT_ACTION_POTENTIAL_CLOCK_DT );
 

js/neuron/model/PotassiumIon.js

@@ -1,5 +1,8 @@
 // Copyright 2002-2011, University of Colorado
+
 /**
+ * Model representation of a sodium ion.
+ *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)
  */

js/neuron/model/PotassiumLeakageChannel.js

@@ -1,7 +1,8 @@
 // Copyright 2002-2011, University of Colorado
 
 /**
- * A gated channel through which potassium passes when the channel is open.
+ * Model representation of a membrane channel through which potassium 'leaks', meaning that it is always passing
+ * through and there is no gating action.
  *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/model/SodiumIon.js

@@ -1,5 +1,7 @@
 // Copyright 2002-2011, University of Colorado
 /**
+ * Model representation of a sodium ion.
+ *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)
  */

js/neuron/model/SodiumLeakageChannel.js

@@ -1,5 +1,8 @@
 // Copyright 2002-2011, University of Colorado
+
 /**
+ * Model representation of a membrane channel through which sodium 'leaks', meaning that it is always passing through
+ * and there is no gating action.
  *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/model/SpeedChangeLinearMotionStrategy.js

@@ -2,8 +2,8 @@
 /**
  * This is a very specialized motion strategy that is basically a linear
  * motion but that starts at one speed and then changes to another.  It was
- * created for a very specific application - getting particles to move quickly
- * away from the exit of a channel with an inactivation gate, and then slowing
+ * created for a specific application - getting particles to move quickly away
+ * from the exit of a channel with an inactivation gate, and then slowing
  * down.  It may have other applications.
  *
  * @author John Blanco

js/neuron/model/StillnessMotionStrategy.js

@@ -1,7 +1,6 @@
 //  Copyright 2002-2014, University of Colorado Boulder
 /**
- * Motion strategy that does not do any motion, i.e. just leaves the model
- * element in the same location.
+ * Motion strategy that does not do any motion, i.e. just leaves the model element in the same location.
  *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/model/TimedFadeAwayStrategy.js

@@ -1,5 +1,10 @@
 // Copyright 2002-2011, University of Colorado
-/*
+
+/**
+ * A strategy that controls how a visible object fades out.  For this particular strategy, fading is based completely
+ * on time, as opposed to position or some other parameter.  Works in conjunction with model elements that have the
+ * appropriate API for fading.
+ *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)
  */

js/neuron/model/TimedFadeInStrategy.js

@@ -1,6 +1,8 @@
 // Copyright 2002-2011, University of Colorado
 
-/*
+/**
+ * A strategy that controls fading in for a particle based on time.
+ *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)
  */

js/neuron/model/TravelingActionPotential.js

@@ -89,10 +89,11 @@ define( function( require ) {
      * Update the shape as a function of the current value of the lifetime
      * counter.
      *
-     * NOTE: An attempt was made to generalize this so that it would work
-     * for pretty much any shape of the axon body, but this turned out to
-     * be a lot of work.  As a result, if significant changes are made to
-     * the axon body shape, this routine will need to be updated.
+     * NOTE: An attempt was made to generalize this so that it would work for
+     * pretty much any shape of the axon body, but this turned out to be a lot
+     * of work, so ultimately we went with a simpler implementation that makes
+     * some assumptions about the axon body shape.  If significant changes are
+     * made to the axon body shape, this routine will need to be updated.
      */
     updateShape: function() {
       if ( this.travelTimeCountdownTimer > 0 ) {

js/neuron/model/TravelingActionPotentialState.js

@@ -1,6 +1,9 @@
 //  Copyright 2002-2014, University of Colorado Boulder
 
 /**
+ * State of the action potential that is traveling down the axon.  This is used primarily to support record and
+ * playback.
+ *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)
  */

js/neuron/recordandplayback/DataPoint.js

@@ -1,9 +1,8 @@
 // Copyright 2002-2011, University of Colorado
 /**
- * The DataPoint is the basic data structure in recording, it keeps track of a state  (which should be immutable)
+ * The DataPoint is the basic data structure in recording, it keeps track of a state (which should be immutable)
  * and pairs it with a time at which the state occurred.
  *
- * The type of the state (should be immutable), possibly a memento pattern for recording a model state.
  * @author Sam Reid
  * @author Sharfudeen Ashraf (for Ghent University)
  */

js/neuron/recordandplayback/Live.js

@@ -1,7 +1,9 @@
 // Copyright 2002-2011, University of Colorado
 
 
-/*
+/**
+ * Type representing the 'live' mode within the RecordAndPlaybackModel.
+ *
  * @author Sam Reid
  * @author Sharfudeen Ashraf (for Ghent University)
  */

js/neuron/recordandplayback/Mode.js

@@ -1,8 +1,7 @@
 // Copyright 2002-2011, University of Colorado
 
 /**
- * Base class representing a Mode in Record and PlayBack Model
- * The mode can be either playback, record or live
+ * Base type representing a Mode in Record and PlayBack Model. The mode can be either playback, record or live.
  *
  * @author Sam Reid
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/recordandplayback/Playback.js

@@ -1,7 +1,7 @@
 // Copyright 2002-2011, University of Colorado
 
 /**
- * Class representing Record Mode
+ * Type representing the 'playback' mode within the RecordAndPlaybackModel.
  *
  * @author Sam Reid
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/recordandplayback/Record.js

@@ -1,7 +1,7 @@
 // Copyright 2002-2011, University of Colorado
 
 /**
- * Class representing Record Mode
+ * Type representing the 'record' mode within the RecordAndPlaybackModel.
  *
  * @author Sam Reid
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/recordandplayback/RecordAndPlaybackModel.js

@@ -1,9 +1,14 @@
 //  Copyright 2002-2014, University of Colorado Boulder
 
+//REVIEW - This header comment is quite different from the one in the Java version of this class.  If this is
+// basically a port of the Java version, please incorporate the original comment so that we can more easily pull
+// this out into a separate library if desired.  If significant deviations from the original version of
+// RecordAndPlaybackModel have occurred, we should discuss.
 /**
  * The Neuron Model delegates all the animations through RecordAndPlaybackModel.
  * This class as of now acts only as a stub and  simply dispatches the step animation back to the Neuron Model
  * This stub is created in order keep NeuronModel's code intact as it makes multiple references to this class
+ *
  * @author Sam Reid
  * @author Sharfudeen Ashraf
  */

js/neuron/view/ParticleSpriteSheetNode.js

@@ -1,4 +1,7 @@
 // Copyright 2002-2011, University of Colorado
+
+//REVIEW - This comment could use some cleanup.  Should it be retained even though it is only for debug?  If so,
+// please state why.
 /**
  * The Node instances is meant for debugging purpose only
  * (During development we can attach it to a scenegraph node to see how particle tiles are laid out)

js/neuron/view/ParticlesNode.js

@@ -1,6 +1,11 @@
 // Copyright 2002-2011, University of Colorado
+
+//REVIEW - The comment below says that this is replaced, yet I see references in a few places.  Is it still used?  If
+//so, the comment should be updated.  If not, it should be removed or the documentation should explain why it should be
+//kept around.
+
 /**
- * For performance  reason uses a single canvasNode  to render all the particles.
+ * For performance reasons this sim uses a single canvasNode to render all the particles.
  * This class is replaced by ParticlesWebGLNode which uses WebGL to render the particles
  *
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/view/ParticlesWebGLNode.js

@@ -1,5 +1,6 @@
 // Copyright 2002-2014, University of Colorado Boulder
 
+//REVIEW - Please clean up this comment using the 120 column guideline specified in the PhET Development Overview.
 /**
  * Particles Node, rendered in WebGL to improve performance
  * Particles are rendered by mapping their rectangular corners with a dynamically created SpriteSheet tiles.
@@ -84,6 +85,7 @@ define( function( require ) {
     this.tilePosVector = new Vector2();
     this.viewTransformationMatrix = thisNode.modelViewTransform.getMatrix();
     this.particleViewPosition = new Vector2();
+    //REVIEW - This variable appears to be unused.
     this.viewPortPosition = new Vector3();
 
     this.invalidatePaint();

js/neuron/view/TransientParticlesNode.js

@@ -1,4 +1,6 @@
 // Copyright 2002-2011, University of Colorado
+
+//REVIEW - Header comment needed.
 /**
  *
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/view/TravelingActionPotentialNode.js

@@ -1,5 +1,7 @@
 // Copyright 2002-2011, University of Colorado
 /**
+ * Class that visually represents the action potential that travels down the membrane prior to reaching the cross
+ * section.  It is meant to look sort of 'electric' or 'energetic'.
  *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/view/ZoomControl.js

@@ -1,6 +1,7 @@
 //  Copyright 2002-2014, University of Colorado Boulder
+
 /**
- * A class to control the zoom factor.
+ * A Scenery node that can be used to control the zoom factor.
  *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)
@@ -19,6 +20,7 @@ define( function( require ) {
   var Util = require( 'DOT/Util' );
   var RectangularButtonView = require( 'SUN/buttons/RectangularButtonView' );
 
+  //REVIEW - neuronModel appears to be unused.  Can it be removed?
   /**
    * @param {NeuronModel} neuronModel - the main model for the simulation
    * @param {Property.<number>} zoomProperty - property that indicates how far zoomed in the simulation is, between
@@ -49,7 +51,7 @@ define( function( require ) {
       return ctrlButton;
     }
 
-    var sideLength = 24;// length of one side of the button
+    var sideLength = 24; // length of one side of the button, empirically determined
     var symbolLength = 0.5 * sideLength;
     var symbolLineWidth = 0.12 * sideLength;
 
@@ -69,6 +71,7 @@ define( function( require ) {
       centerX: sideLength / 2,
       centerY: sideLength / 2
     };
+
     var plusButton = createZoomControlButton( new Path( plusSymbolShape, symbolOptions ), {xMargin: 6, yMargin: 6}, function() {
       zoomProperty.set( Util.clamp( zoomProperty.value + 0.1, minZoom, maxZoom ) );
     } );

js/neuron/view/ZoomableNode.js

@@ -1,7 +1,8 @@
 //  Copyright 2002-2014, University of Colorado Boulder
-// This node is a container for AxonBody,cross section,
-// channels all of which needs to be zoomed in and out together
+
 /**
+ * This node is a container for the axon body, the cross section, and the membrane channels, all of which needs to be
+ * zoomed in and out together.
  *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)
@@ -29,9 +30,8 @@ define( function( require ) {
     Node.call( thisNode, { clipArea: clipArea } );
     zoomProperty.link( function( zoomFactor ) {
 
-      // Zoom toward the top so that when zoomed in the membrane
-      // is in a reasonable place and there is room for the chart below
-      // it.
+      // Zoom toward the top so that when zoomed in the membrane is in a reasonable place and there is room for the
+      // chart below it.
       var zoomTowardTopThreshold = 0.6;
       var scaleMatrix;
       var scaleAroundX = Math.round( viewPortPosition.x );