improve phet-io tree for screen 1, see #63

js/coins/model/CoinsExperimentSceneModel.ts

@@ -65,7 +65,7 @@ export default class CoinsExperimentSceneModel extends PhetioObject {
   // The initial state of the coin(s) before any flipping or other experiment preparation occurs.
   public readonly initialCoinStateProperty: Property<ClassicalCoinStates> | Property<QuantumUncollapsedCoinStates>;
 
-  // The probability of the 'up' state. The 'down' probability will be 1 - this.
+  // The probability of the 'up' state. The 'down' probability will be (1 - thisValue).
   public readonly upProbabilityProperty: NumberProperty;
 
   public constructor( providedOptions: CoinExperimentSceneModelOptions ) {
@@ -82,15 +82,17 @@ export default class CoinsExperimentSceneModel extends PhetioObject {
     this.systemType = options.systemType;
 
     this.activeProperty = new BooleanProperty( options.initiallyActive, {
-      tandem: options.tandem.createTandem( 'activeProperty' )
+      tandem: options.tandem.createTandem( 'activeProperty' ),
+      phetioReadOnly: true
     } );
     this.preparingExperimentProperty = new BooleanProperty( true, {
       tandem: options.tandem.createTandem( 'preparingExperimentProperty' )
     } );
     this.upProbabilityProperty = new NumberProperty( options.initialBias, {
       range: new Range( 0, 1 ),
       tandem: options.tandem.createTandem( 'upProbabilityProperty' ),
-      phetioFeatured: true
+      phetioFeatured: true,
+      phetioDocumentation: 'The probability of the "up" state for the coin(s) in this scene.'
     } );
     const singleCoinTandem = options.tandem.createTandem( 'singleCoin' );
     const coinSetTandem = options.tandem.createTandem( 'coinSet' );

js/coins/model/CoinsModel.ts

@@ -41,7 +41,9 @@ export default class CoinsModel implements TModel {
 
     this.experimentTypeProperty = new Property<SystemType>( 'classical', {
       tandem: providedOptions.tandem.createTandem( 'experimentTypeProperty' ),
-      phetioValueType: StringUnionIO( SystemTypeValues )
+      phetioValueType: StringUnionIO( SystemTypeValues ),
+      validValues: SystemTypeValues,
+      phetioFeatured: true
     } );
 
     // Update the active scene model based on the experiment type.

js/common/model/TwoStateSystem.ts

@@ -35,7 +35,8 @@ export default class TwoStateSystem<T extends string> extends TwoStateSystemSet<
       tandem: options.tandem.createTandem( 'measuredValueProperty' ),
       phetioValueType: StringUnionIO( stateValues ),
       validValues: [ ...stateValues ],
-      phetioFeatured: true
+      phetioFeatured: true,
+      phetioReadOnly: true
     } );
 
     // Hook up to the data-changed emitter to update the data Property.

js/common/model/TwoStateSystemSet.ts

@@ -18,7 +18,9 @@ import Range from '../../../../dot/js/Range.js';
 import optionize from '../../../../phet-core/js/optionize.js';
 import PickRequired from '../../../../phet-core/js/types/PickRequired.js';
 import PhetioObject, { PhetioObjectOptions } from '../../../../tandem/js/PhetioObject.js';
+import Tandem from '../../../../tandem/js/Tandem.js';
 import StringUnionIO from '../../../../tandem/js/types/StringUnionIO.js';
+import { MULTI_COIN_EXPERIMENT_QUANTITIES } from '../../coins/model/CoinsExperimentSceneModel.js';
 import { ExperimentMeasurementState, ExperimentMeasurementStateValues } from '../../coins/model/ExperimentMeasurementState.js';
 import quantumMeasurement from '../../quantumMeasurement.js';
 import { SystemType } from './SystemType.js';
@@ -96,11 +98,19 @@ export default class TwoStateSystemSet<T extends string> extends PhetioObject {
     this.validValues = stateValues;
     this.systemType = options.systemType;
 
-    this.numberOfActiveSystemsProperty = new NumberProperty( initialNumberOfActiveSystems, {
-      tandem: options.tandem.createTandem( 'numberOfActiveSystemsProperty' ),
-      phetioFeatured: true,
-      validValues: maxNumberOfActiveSystems === 1 ? [ 1 ] : [ 10, 100, 10000 ]
-    } );
+    // The nature of the number of active systems Property is different for the single coin versus the multi-coin case.
+    if ( maxNumberOfActiveSystems === 1 ) {
+      this.numberOfActiveSystemsProperty = new NumberProperty( initialNumberOfActiveSystems, {
+        tandem: Tandem.OPT_OUT
+      } );
+    }
+    else {
+      this.numberOfActiveSystemsProperty = new NumberProperty( initialNumberOfActiveSystems, {
+        tandem: options.tandem.createTandem( 'numberOfActiveSystemsProperty' ),
+        phetioFeatured: true,
+        validValues: MULTI_COIN_EXPERIMENT_QUANTITIES
+      } );
+    }
 
     // The initial system state differs for classical versus quantum systems.
     const initialMeasurementState = this.systemType === 'classical' ? 'measuredAndHidden' : 'readyToBeMeasured';
@@ -113,11 +123,12 @@ export default class TwoStateSystemSet<T extends string> extends PhetioObject {
     this.biasProperty = biasProperty;
     this.measuredValues = new Array<T>( maxNumberOfActiveSystems );
 
-    // Create the seed Property.  It's initial value is controlled by the specified initial value for measurements.
+    // Create the seed Property.  Its initial value is controlled by the specified initial value for measurements.
     this.seedProperty = new NumberProperty( stateValues.indexOf( initialState ), {
       range: new Range( 0, 1 ),
       tandem: options.tandem.createTandem( 'seedProperty' ),
-      phetioFeatured: true
+      phetioReadOnly: true,
+      phetioDocumentation: 'The seed that is used to generate the most recent set of measured values.'
     } );
 
     // Monitor the seed that is used to create the measurement values.
@@ -252,8 +263,9 @@ export default class TwoStateSystemSet<T extends string> extends PhetioObject {
    */
   private generateNewRandomMeasurementValues(): void {
 
-    // New values are generated by create a new random seed and setting it.  The listener for the seedProperty does the
-    // actual generation.  Note that the value of 0 is not allowed because it has special significance.
+    // New values are generated by creating a new random seed and setting the value of a Property.  A listener for this
+    // Property does the actual generation of the values.  Note that the value of 0 is not allowed for the random seed
+    // because it has special significance - it means all the values should be set to 0.
     let newSeed;
     do {
       newSeed = dotRandom.nextDouble();