documentation on flow,#298

phetsims · Sep 27, 2017 · 4970563 · 4970563
1 parent ec17076
commit 4970563
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 25 deletions.
diff --git a/js/flow/model/FlowModel.js b/js/flow/model/FlowModel.js
@@ -51,21 +51,36 @@ define( function( require ) {
   function FlowModel() {
     var self = this;
 
+    // @public (read-only)
     this.fluidDensityRange = new RangeWithValue( Constants.GASOLINE_DENSITY, Constants.HONEY_DENSITY );
     this.flowRateRange = new RangeWithValue( Constants.MIN_FLOW_RATE, Constants.MAX_FLOW_RATE );
 
-    this.isRulerVisibleProperty = new Property( false ); // TODO: Appears unused
+
+    // @public
+    this.isRulerVisibleProperty = new Property( false );
     this.isFluxMeterVisibleProperty = new Property( false );
     this.isGridInjectorPressedProperty = new Property( false );
-    this.gridInjectorElapsedTimeInPressedModeProperty = new Property( 0 ); // elapsed sim time (in sec) for which the injector remained pressed
+
+    // elapsed sim time (in sec) for which the injector has been pressed
+    this.gridInjectorElapsedTimeInPressedModeProperty = new Property( 0 );
     this.isDotsVisibleProperty = new Property( true );
-    this.isPlayingProperty = new Property( true );// Whether the sim is paused or running
-    this.measureUnitsProperty = new Property( 'metric' ); //metric, english
-    this.fluidDensityProperty = new Property( Constants.WATER_DENSITY );
-    this.fluidDensityControlExpandedProperty = new Property( false ); // TODO: appears unused
-    this.flowRateControlExpandedProperty = new Property( false ); // TODO: appears unused
-    this.rulerPositionProperty = new Property( new Vector2( 300, 344 ) ); // px // TODO: Appears unused
-    this.speedProperty = new Property( 'normal' ); //speed of the model, either 'normal' or 'slow'
+    this.isPlayingProperty = new Property( true ); // Whether the sim is paused or running
+
+    // {Property.<string>} - can be either "metric" "atmospheres or "english"
+    this.measureUnitsProperty = new Property( 'metric' );
+    this.fluidDensityProperty = new Property( Constants.WATER_DENSITY ); // {Property.<number>}
+
+    // Used to default the density accordion box to be closed
+    this.fluidDensityControlExpandedProperty = new Property( false );
+
+    // Used to default the flow rate accordion boxes to be closed
+    this.flowRateControlExpandedProperty = new Property( false );
+
+    // in px, here set the default position of the ruler on display
+    this.rulerPositionProperty = new Property( new Vector2( 300, 344 ) );
+
+    // {Property.<string>} - speed of the model, either 'normal' or 'slow'
+    this.speedProperty = new Property( 'normal' );
 
     this.barometers = [];
     for ( var i = 0; i < NUMBER_BAROMETERS; i++ ) {
@@ -85,6 +100,12 @@ define( function( require ) {
     this.flowParticles = new ObservableArray();
     this.gridParticles = new ObservableArray();
 
+    // call stepInternal at a rate of 10 times per second
+    this.timer = new EventTimer( new EventTimer.UniformEventModel( 10, Math.random ), function() {
+      self.createParticle();
+    } );
+    // end @public members
+
     this.gridInjectorElapsedTimeInPressedModeProperty.link( function( elapsedTime ) {
 
       //  The grid injector can only be fired every so often, in order to prevent too many black particles in the pipe
@@ -93,11 +114,6 @@ define( function( require ) {
         self.gridInjectorElapsedTimeInPressedModeProperty.value = 0;
       }
     } );
-
-    // call stepInternal at a rate of 10 times per second
-    this.timer = new EventTimer( new EventTimer.UniformEventModel( 10, Math.random ), function() {
-      self.createParticle();
-    } );
   }
 
   fluidPressureAndFlow.register( 'FlowModel', FlowModel );
@@ -180,7 +196,7 @@ define( function( require ) {
         dt = ( dt > 0.04 ) ? 0.04 : dt;
 
         if ( this.isPlayingProperty.value ) {
-          var adjustedDT = this.speedProperty.value === 'normal' ? dt : dt * 0.33;
+          var adjustedDT = this.speedProperty.value === 'normal' ? dt : dt * 0.33; // if not 'normal' then it is 'slow'
           this.timer.step( adjustedDT );
           this.propagateParticles( adjustedDT );
           if ( this.isGridInjectorPressedProperty.value ) {

diff --git a/js/flow/view/FlowToolsControlPanel.js b/js/flow/view/FlowToolsControlPanel.js
@@ -50,13 +50,13 @@ define( function( require ) {
 
     // itemSpec describes the pieces that make up an item in the control panel,
     // conforms to the contract: { label: {Node}, icon: {Node} (optional) }
-    var ruler = { label: new Text( rulerString, textOptions ), icon: createRulerIcon() };
-    var friction = { label: new Text( frictionString, textOptions ) };
-    var fluxMeter = { label: new Text( fluxMeterString, textOptions ) };
-    var dots = { label: new Text( dotsString, textOptions ), icon: createDotsIcon() };
+    var rulerSpec = { label: new Text( rulerString, textOptions ), icon: createRulerIcon() };
+    var frictionSpec = { label: new Text( frictionString, textOptions ) };
+    var fluxMeterSpec = { label: new Text( fluxMeterString, textOptions ) };
+    var dotsSpec = { label: new Text( dotsString, textOptions ), icon: createDotsIcon() };
 
     // compute the maximum item width
-    var widestItemSpec = _.maxBy( [ ruler, friction, fluxMeter, dots ], function( item ) {
+    var widestItemSpec = _.maxBy( [ rulerSpec, frictionSpec, fluxMeterSpec, dotsSpec ], function( item ) {
       return item.label.width + ((item.icon) ? item.icon.width : 0);
     } );
     var maxWidth = widestItemSpec.label.width + ((widestItemSpec.icon) ? widestItemSpec.icon.width : 0);
@@ -77,11 +77,11 @@ define( function( require ) {
       spacing: 2
     };
 
-    var rulerCheckBox = new CheckBox( createItem( ruler ), flowModel.isRulerVisibleProperty, checkBoxOptions );
-    var frictionCheckBox = new CheckBox( createItem( friction ), flowModel.pipe.frictionProperty, checkBoxOptions );
-    var fluxMeterCheckBox = new CheckBox( createItem( fluxMeter ), flowModel.isFluxMeterVisibleProperty,
+    var rulerCheckBox = new CheckBox( createItem( rulerSpec ), flowModel.isRulerVisibleProperty, checkBoxOptions );
+    var frictionCheckBox = new CheckBox( createItem( frictionSpec ), flowModel.pipe.frictionProperty, checkBoxOptions );
+    var fluxMeterCheckBox = new CheckBox( createItem( fluxMeterSpec ), flowModel.isFluxMeterVisibleProperty,
       checkBoxOptions );
-    var dotsCheckBox = new CheckBox( createItem( dots ), flowModel.isDotsVisibleProperty, checkBoxOptions );
+    var dotsCheckBox = new CheckBox( createItem( dotsSpec ), flowModel.isDotsVisibleProperty, checkBoxOptions );
 
     var maxCheckBoxWidth = _.maxBy( [ rulerCheckBox, frictionCheckBox, fluxMeterCheckBox, dotsCheckBox ],
         function( item ) {

diff --git a/js/flow/view/FluxMeterNode.js b/js/flow/view/FluxMeterNode.js
@@ -261,7 +261,7 @@ define( function( require ) {
         this.fluxValue.text = this.flowModel.fluxMeter.getFlux().toFixed( 1 );
         this.fluxUnit.text = fluxUnitsMetricString;
       }
-      else {
+      else { // use english for either english or atmospheres
         var flowRate = this.flowModel.fluxMeter.getFlowRate() * Units.FEET_CUBE_PER_LITER;
         this.flowRateValue.text = flowRate.toFixed( 1 );
         this.flowRateUnit.text = rateUnitsEnglishString;