minor formatting and documentation, #30

js/common/model/MPModel.js

@@ -44,7 +44,7 @@ define( function( require ) {
     if ( normalizedAngle < 0 ) {
       normalizedAngle = ( 2 * Math.PI ) + angle;
     }
-    assert && assert( normalizedAngle >= 0 && normalizedAngle <= 2 * Math.PI );
+    assert && assert( normalizedAngle >= 0 && normalizedAngle <= 2 * Math.PI, 'normalizedAngle must be between 0-2pi radians' );
     return normalizedAngle;
   };
 

js/common/view/MoleculeAngleDragHandler.js

@@ -22,7 +22,7 @@ define( function( require ) {
 
     var previousAngle; // angle between the pointer and the molecule when the drag started
 
-    /*
+    /**
      * Gets the angle of the pointer relative to relativeNode.
      * @param {Event} event
      * @returns {number} angle in radians

js/common/view/PartialChargeNode.js

@@ -3,6 +3,7 @@
 /**
  * Visual representations of partial charge, a delta symbol followed by either + or -.
  * Controls its own position in global coordinates, so clients should not attempt to position it.
+ * Uses static factory methods to supply the needed instances for the sim.
  *
  * @author Chris Malley (PixelZoom, Inc.)
  */
@@ -54,6 +55,7 @@ define( function( require ) {
 
       textNode.visible = ( partialCharge !== 0 ); // invisible if dipole is zero
 
+      // Only update if there is a charge difference
       if ( partialCharge !== 0 ) {
 
         // d+ or d-
@@ -85,7 +87,7 @@ define( function( require ) {
 
   return inherit( Node, PartialChargeNode, {}, {
 
-    /*
+    /**
      * Partial charge for an atom that participates in a single bond.
      * It's partial charge is the opposite of the charge of the other atom in the bond.
      * The charge is placed along the axis of the bond, away from the atom.
@@ -114,13 +116,13 @@ define( function( require ) {
       } );
     },
 
-    /*
+    /**
      * Partial charge for an atom that participates in more than one bond.
      * Its partial charge is the composite of charges contributed by other atoms in the bonds.
      * The charge is placed along the axis of the molecular dipole, on the opposite side of the atom from the dipole.
      * @static
      * @param {Atom} atom
-     * @param {Bond} bond
+     * @param {Molecule} molecule
      * @returns {PartialChargeNode}
      * @public
      * @static

js/realmolecules/view/JSmolViewerNode.js

@@ -232,7 +232,7 @@ define( function( require ) {
      * Eg, for HF: ['1','255','255','255','9','144','224','80']
      */
     var tokens = status.split( ' ' );
-    assert && assert( tokens.length % 4 === 0 ); // each element has 4 tokens
+    assert && assert( tokens.length % 4 === 0, 'each element should have 4 tokens' );
 
     // Convert the tokens to an array of {Element}.
     var elements = [];
@@ -402,7 +402,7 @@ define( function( require ) {
     // Call this after the sim has started running
     initialize: function() {
 
-      assert && assert( !this.isInitialized() );
+      assert && assert( !this.isInitialized(), 'already initialized' );
 
       var self = this;
 

js/threeatoms/view/TranslateArrowsNode.js

@@ -45,6 +45,7 @@ define( function( require ) {
 
     // unlink not needed
     atom.locationProperty.link( function() {
+
       // transform the arrow shapes to account for atom location and relationship to molecule location
       var v = molecule.location.minus( atom.locationProperty.get() );
       var angle = v.angle() - ( Math.PI / 2 );

js/twoatoms/view/BondCharacterNode.js

@@ -1,7 +1,9 @@
 // Copyright 2014-2017, University of Colorado Boulder
 
 /**
- * Displays the bond 'character', by placing a marker on a continuum whose extremes are "covalent" and "ionic".
+ * Displays the bond 'character' of the molecule, by placing a marker on a continuum whose extremes are "covalent"
+ * and "ionic". This node is derived; the marker serves as a "readout" and is updated based on the properties
+ * of the molecule.
  *
  * @author Chris Malley (PixelZoom, Inc.)
  */

js/twoatoms/view/DiatomicMoleculeNode.js

@@ -46,6 +46,7 @@ define( function( require ) {
 
     Node.call( this, {
       children: [
+
         // rendering order
         this.electrostaticPotentialNode, this.electronDensityNode,
         bondNode, atomANode, atomBNode,

js/twoatoms/view/ElectronDensityNode.js

@@ -34,7 +34,7 @@ define( function( require ) {
    */
   function ElectronDensityNode( molecule ) {
 
-    assert && assert( molecule.atomA.diameter === molecule.atomB.diameter ); // creation of gradient assumes that both atoms have the same diameter
+    assert && assert( molecule.atomA.diameter === molecule.atomB.diameter, 'creation of gradient assumes that both atoms have the same diameter' );
 
     var self = this;
 
@@ -44,7 +44,7 @@ define( function( require ) {
     this.molecule = molecule;
     this.electronegativityRange = MPConstants.ELECTRONEGATIVITY_RANGE;
     this.colors = MPColors.BW_GRADIENT;
-    assert && assert( this.colors.length === 2 ); // this implementation only works for 2 colors
+    assert && assert( this.colors.length === 2, 'this implementation only works for 2 colors' );
 
     // each atom is surrounded with a 'cloud' (circle)
     var radius = this.molecule.atomA.diameter * DIAMETER_SCALE / 2;

js/twoatoms/view/ElectrostaticPotentialNode.js

@@ -34,7 +34,8 @@ define( function( require ) {
    */
   function ElectrostaticPotentialNode( molecule ) {
 
-    assert && assert( molecule.atomA.diameter === molecule.atomB.diameter ); // creation of gradient assumes that both atoms have the same diameter
+    assert && assert( molecule.atomA.diameter === molecule.atomB.diameter,
+      'creation of gradient assumes that both atoms have the same diameter' );
 
     var self = this;
 
@@ -44,7 +45,7 @@ define( function( require ) {
     this.molecule = molecule;
     this.electronegativityRange = MPConstants.ELECTRONEGATIVITY_RANGE;
     this.colors = MPColors.RWB_GRADIENT;
-    assert && assert( this.colors.length === 3 ); // this implementation only works for 3 colors
+    assert && assert( this.colors.length === 3, 'this implementation only works for 3 colors' );
 
     // each atom is surrounded with a 'cloud' (circle)
     var radius = this.molecule.atomA.diameter * DIAMETER_SCALE / 2;
@@ -79,7 +80,10 @@ define( function( require ) {
 
   return inherit( Node, ElectrostaticPotentialNode, {
 
-    // @public @override
+    /**
+     * @override
+     * @public
+     */
     setVisible: function( visible ) {
       Node.prototype.setVisible.call( this, visible );
       if ( visible ) {
@@ -88,11 +92,12 @@ define( function( require ) {
       }
     },
 
-    /*
+    /**
      * Updates the surface fill. Width of the gradient expands as the difference in EN approaches zero.
      * @private
      */
     updateFill: function() {
+
       // scale varies from 1 to 0, approaches zero as EN difference approaches zero.
       var deltaEN = this.molecule.getDeltaEN();
       if ( deltaEN === 0 ) {

js/twoatoms/view/TwoAtomsScreenView.js

@@ -59,6 +59,7 @@ define( function( require ) {
     // Parent for all nodes added to this screen
     var rootNode = new Node( {
       children: [
+
         // nodes are rendered in this order
         negativePlateNode,
         positivePlateNode,