code cleanup, mostly adding annotations and making comments the right…

… length, see #29

js/neuron/common/MathUtils.js

@@ -18,6 +18,7 @@ define( function( require ) {
   var distanceCalculatorVectorRHS = new Vector2();
 
   return {
+
     /**
      * A method to calculate distance by reusing vector instances. This method is created to reduce Vector2 instance
      * allocation during distance calculation.

js/neuron/model/AbstractLeakChannel.js

@@ -27,12 +27,15 @@ define( function( require ) {
 
   return inherit( MembraneChannel, AbstractLeakChannel, {
 
+    // @public
     stepInTime: function( dt ) {
       MembraneChannel.prototype.stepInTime.call( this, dt );
     },
 
+    // @public
     reset: function() {
       this.setOpenness( 1 );  // Leak channels are always fully open.
     }
+
   } );
 } );

js/neuron/model/CaptureZone.js

@@ -19,23 +19,27 @@ define( function( require ) {
 
   return inherit( Object, CaptureZone, {
 
+    // @public
     isPointInZone: function( x, y ) {
       throw new Error( 'isPointInZone should be implemented in descendant classes.' );
     },
 
-    // assign a random point that is somewhere within the shape.
+    // @public, assign a random point that is somewhere within the shape.
     assignNewParticleLocation: function( particle ) {
       particle.setPosition( 0, 0 );
     },
 
+    // @public
     getOriginPoint: function() {
       throw new Error( 'getOriginPoint should be implemented in descendant classes.' );
     },
 
+    // @public
     setRotationalAngle: function( angle ) {
       throw new Error( 'setRotationalAngle should be implemented in descendant classes.' );
     },
 
+    // @public
     setOriginPoint: function( centerPoint ) {
       throw new Error( 'setOriginPoint should be implemented in descendant classes.' );
     }

js/neuron/model/DelayBuffer.js

@@ -18,8 +18,8 @@ define( function( require ) {
   var DelayElement = require( 'NEURON/neuron/model/DelayElement' );
   var Util = require( 'DOT/Util' );
 
-  // This value is used to tell if two numbers are different.  It was needed
-  // due to some floating point resolution problems that were occurring.
+  // This value is used to tell if two numbers are different.  It was needed due to some floating point resolution
+  // problems that were occurring.
   var DIFFERENCE_RESOLUTION = 1E-15;
 
   /**
@@ -29,27 +29,28 @@ define( function( require ) {
    */
   function DelayBuffer( maxDelay, minTimeStep ) {
     var thisBuffer = this;
-    thisBuffer.numEntries = Math.ceil( maxDelay / minTimeStep );
-    thisBuffer.filling = false;
-    thisBuffer.allDeltaTimesEqual = true;
-    thisBuffer.previousDeltaTime = -1;
-    thisBuffer.countAtThisDeltaTime = 0;
+    thisBuffer.numEntries = Math.ceil( maxDelay / minTimeStep ); // @private
+    thisBuffer.filling = false; // @private
+    thisBuffer.allDeltaTimesEqual = true; // @private
+    thisBuffer.previousDeltaTime = -1; // @private
+    thisBuffer.countAtThisDeltaTime = 0; // @private
     // Allocate the memory that will be used.
-    thisBuffer.delayElements = new Array( this.numEntries );
+    thisBuffer.delayElements = new Array( this.numEntries ); // @private
 
     _.times( this.numEntries, function( idx ) {
       thisBuffer.delayElements[ idx ] = new DelayElement();
     } );
 
     // Head and tail pointers for FIFO-type behavior.
-    thisBuffer.head = 0;
-    thisBuffer.tail = 0;
+    thisBuffer.head = 0; // @private
+    thisBuffer.tail = 0; // @private
     // Set the initial conditions.
     thisBuffer.clear();
   }
 
   return inherit( Object, DelayBuffer, {
 
+    // @public
     addValue: function( value, deltaTime ) {
       this.delayElements[ this.head ].setValueAndTime( value, deltaTime );
       this.head = (this.head + 1) % this.numEntries;
@@ -94,6 +95,7 @@ define( function( require ) {
       }
     },
 
+    // @public
     getDelayedValue: function( delayAmount ) {
       var delayedValue = 0;
       var index = -1;
@@ -154,6 +156,7 @@ define( function( require ) {
       return delayedValue;
     },
 
+    // @public
     clear: function() {
       this.head = 0;
       this.tail = 0;

js/neuron/model/DelayElement.js

@@ -26,6 +26,8 @@ define( function( require ) {
   }
 
   return inherit( Object, DelayElement, {
+
+    // @public
     setValueAndTime: function( value, deltaTime ) {
       this.value = value;
       this.deltaTime = deltaTime;

js/neuron/model/GatedChannel.js

@@ -26,6 +26,7 @@ define( function( require ) {
 
   return inherit( MembraneChannel, GatedChannel, {
 
+    // @public
     reset: function() {
       this.setOpenness( 0 );         // Gated channels are assumed to be initially closed...
       this.setInactivationAmt( 0 );  // ...but not inactivated.

js/neuron/model/LinearMotionStrategy.js

@@ -23,6 +23,7 @@ define( function( require ) {
 
   return inherit( MotionStrategy, LinearMotionStrategy, {
 
+    // @public
     move: function( movableModelElement, fadableModelElement, dt ) {
       var currentPositionRefX = movableModelElement.getPositionX();
       var currentPositionRefY = movableModelElement.getPositionY();

js/neuron/model/MembraneChannel.js

@@ -355,7 +355,6 @@ define( function( require ) {
      * @public
      */
     setState: function( state ) {
-
       var prevOpenness = this.getOpenness();
       var prevInactivationAmt = this.getInactivationAmt();
       this.setOpenness( state.getOpenness() );

js/neuron/model/MembraneChannelState.js

@@ -14,7 +14,6 @@ define( function( require ) {
   var inherit = require( 'PHET_CORE/inherit' );
 
   /**
-   *
    * @param {MembraneChannel} membraneChannel
    * @constructor
    */
@@ -30,10 +29,12 @@ define( function( require ) {
 
   return inherit( Object, MembraneChannelState, {
 
+    // @public
     getOpenness: function() {
       return this.openness;
     },
 
+    // @public
     getInactivationAmt: function() {
       return this.inactivationAmt;
     }

js/neuron/model/ModifiedHodgkinHuxleyModel.js

@@ -1,10 +1,8 @@
 // Copyright 2002-2015, University of Colorado Boulder
 /**
- * This class is an implementation of the Hodgkin-Huxley model that started
- * from an example taken from the web (see Unfuddle #2121 for more info on
- * this) but that was modified significantly to fit the needs of this
- * simulation.  The main change is that the way that the conductance values
- * are calculated is different, and much simpler.
+ * This class is an implementation of the Hodgkin-Huxley model that started from an example taken from the web (see
+ * Unfuddle #2121 for more info on this) but that was modified significantly to fit the needs of this simulation.  The
+ * main change is that the way that the conductance values are calculated is different, and much simpler.
  * <p/>
  * This was used with permission from the original author of the example.
  *
@@ -35,43 +33,43 @@ define( function( require ) {
   function ModifiedHodgkinHuxleyModel() {
 
     var thisModel = this;
-    thisModel.perNaChannels = 100;
-    thisModel.perKChannels = 100;
-    thisModel.elapsedTime = 0;
-    thisModel.timeSinceActionPotential = Number.POSITIVE_INFINITY;
-    thisModel.m3hDelayBuffer = new DelayBuffer( MAX_DELAY, NeuronConstants.MIN_ACTION_POTENTIAL_CLOCK_DT );
-    thisModel.n4DelayBuffer = new DelayBuffer( MAX_DELAY, NeuronConstants.MIN_ACTION_POTENTIAL_CLOCK_DT );
+    thisModel.perNaChannels = 100; // @private
+    thisModel.perKChannels = 100; // @private
+    thisModel.elapsedTime = 0; // @private
+    thisModel.timeSinceActionPotential = Number.POSITIVE_INFINITY; // @private
+    thisModel.m3hDelayBuffer = new DelayBuffer( MAX_DELAY, NeuronConstants.MIN_ACTION_POTENTIAL_CLOCK_DT ); // @private
+    thisModel.n4DelayBuffer = new DelayBuffer( MAX_DELAY, NeuronConstants.MIN_ACTION_POTENTIAL_CLOCK_DT ); // @private
 
-    thisModel.resting_v = 65;// final doesn't change
+    thisModel.resting_v = 65;// @private, final doesn't change
 
     // deltas of voltage-dependent gating parameters
-    thisModel.dn = 0;
-    thisModel.dm = 0;
-    thisModel.dh = 0;
+    thisModel.dn = 0; // @private
+    thisModel.dm = 0; // @private
+    thisModel.dh = 0; // @private
 
-    thisModel.timeRemainder = 0;
+    thisModel.timeRemainder = 0; // @private
 
     // Ek-Er, Ena - Er, Eleak - Er
-    thisModel.vk = 0;
-    thisModel.vna = 0;
-    thisModel.vl = 0;
+    thisModel.vk = 0; // @private
+    thisModel.vna = 0; // @private
+    thisModel.vl = 0; // @private
 
-    thisModel.n4 = 0;
-    thisModel.m3h = 0;
-    thisModel.na_current = 0;
-    thisModel.k_current = 0;
-    thisModel.l_current = 0;
+    thisModel.n4 = 0; // @private
+    thisModel.m3h = 0; // @private
+    thisModel.na_current = 0; // @private
+    thisModel.k_current = 0; // @private
+    thisModel.l_current = 0; // @private
 
-    thisModel.vClampOn = false;
+    thisModel.vClampOn = false; // @private
 
-    thisModel.vClampValue = this.convertV( 0 );
+    thisModel.vClampValue = this.convertV( 0 ); // @private
 
     thisModel.reset();// reset and initialize
-
   }
 
   return inherit( Object, ModifiedHodgkinHuxleyModel, {
 
+    // @public
     reset: function() {
       this.n4DelayBuffer.clear();
       this.m3hDelayBuffer.clear();
@@ -106,6 +104,7 @@ define( function( require ) {
       this.timeSinceActionPotential = Number.POSITIVE_INFINITY;
     },
 
+    // @public
     stepInTime: function( dt ) {
       var modelIterationsToRun = Math.floor( ( dt * 1000 ) / INTERNAL_TIME_STEP );
       this.timeRemainder += ( dt * 1000 ) % INTERNAL_TIME_STEP;
@@ -183,16 +182,18 @@ define( function( require ) {
       }
     },
 
+    // @public
     get_n4: function() {
       return this.n4;
     },
 
     /**
-     * Get a delayed version of the n^4 amount, which is the variable factor
-     * that governs the potassium channel conductance.
+     * Get a delayed version of the n^4 amount, which is the variable factor that governs the potassium channel
+     * conductance.
      *
      * @param delayAmount - Time delay in seconds.
-     * @return
+     * @return {number}
+     * @public
      */
     get_delayed_n4: function( delayAmount ) {
       if ( delayAmount <= 0 ) {
@@ -203,6 +204,7 @@ define( function( require ) {
       }
     },
 
+    // @public
     get_m3h: function() {
       return this.m3h;
     },
@@ -212,7 +214,8 @@ define( function( require ) {
      * that governs the sodium channel conductance.
      *
      * @param delayAmount - Time delay in seconds.
-     * @return
+     * @return {number}
+     * @public
      */
     get_delayed_m3h: function( delayAmount ) {
       var delayedM3h = 0;

js/neuron/model/MotionStrategy.js

@@ -1,7 +1,6 @@
 // Copyright 2002-2014, University of Colorado Boulder
 /**
- * Base class for motion strategies that can be used to set the type of motion
- * for elements within the model.
+ * Base class for motion strategies that can be used to set the type of motion for elements within the model.
  *
  * @author John Blanco
  * @author Sharfudeen Ashraf (for Ghent University)

js/neuron/model/NeuronClockModelAdapter.js

@@ -51,6 +51,7 @@ define( function( require ) {
 
   return inherit( PropertySet, NeuronClockModelAdapter, {
 
+    // @public
     step: function( dt ) {
 
       // If the step is large, it probably means that the screen was hidden for a while, so just ignore it.
@@ -63,6 +64,7 @@ define( function( require ) {
       }
     },
 
+    // @public
     reset: function() {
       this.lastSimulationTime = 0.0;
       this.simulationTime = 0.0;
@@ -80,20 +82,23 @@ define( function( require ) {
      * Registers a callback that will be notified when the step simulation occurs
      * Neuron Clock uses specialized real time step simulation
      * @param  callback has a {dt} parameter
+     * @public
      */
     registerStepCallback: function( callback ) {
       this.stepCallbacks.push( callback );
     },
 
     /**
      * Registers a callback that will be notified when the clock is reset
+     * @public
      */
     registerResetCallback: function( callback ) {
       this.resetCallBacks.push( callback );
     },
 
     /**
      * Update the clock, updating the wall time and possibly simulation time.
+     * @public
      */
     tick: function( simulationTimeChange ) {
       //fire step event callback