doc, #231

js/common/model/HeavyParticle.ts

@@ -51,9 +51,14 @@ export default class HeavyParticle extends Particle {
     } );
   }
 
+  /**
+   * HeavyParticleIO handles serialization a HeavyParticle. It implements 'Data Type Serialization',
+   * as described in https://github.com/phetsims/phet-io/blob/main/doc/phet-io-instrumentation-technical-guide.md#serialization.
+   */
   public static readonly HeavyParticleIO = new IOType<HeavyParticle, HeavyParticleStateObject>( 'HeavyParticleIO', {
     valueType: HeavyParticle,
-    stateSchema: Particle.STATE_SCHEMA,
+    stateSchema: HeavyParticle.STATE_SCHEMA,
+    // toStateObject: Use the default, which is derived from stateSchema.
     fromStateObject: HeavyParticle.fromStateObject
   } );
 }

js/common/model/LightParticle.ts

@@ -51,9 +51,14 @@ export default class LightParticle extends Particle {
     } );
   }
 
+  /**
+   * LightParticleIO handles serialization a LightParticle. It implements 'Data Type Serialization',
+   * as described in https://github.com/phetsims/phet-io/blob/main/doc/phet-io-instrumentation-technical-guide.md#serialization.
+   */
   public static readonly LightParticleIO = new IOType<LightParticle, LightParticleStateObject>( 'LightParticleIO', {
     valueType: LightParticle,
-    stateSchema: Particle.STATE_SCHEMA,
+    stateSchema: LightParticle.STATE_SCHEMA,
+    // toStateObject: Use the default, which is derived from stateSchema.
     fromStateObject: LightParticle.fromStateObject
   } );
 }

js/common/model/ParticleSystem.ts

@@ -48,13 +48,15 @@ type SelfOptions = {
 
 type ParticleSystemOptions = SelfOptions & PickRequired<PhetioObjectOptions, 'tandem'>;
 
+// This should match PARTICLE_SYSTEM_STATE_SCHEMA, but with JavaScript types.
 type ParticleSystemStateObject = {
   heavyParticles: HeavyParticleStateObject[];
   lightParticles: LightParticleStateObject[];
   heavyParticlesOutside: HeavyParticleStateObject[];
   lightParticlesOutside: LightParticleStateObject[];
 };
 
+// This should match ParticleSystemStateObject, but with IOTypes.
 const PARTICLE_SYSTEM_STATE_SCHEMA = {
   heavyParticles: ArrayIO( HeavyParticle.HeavyParticleIO ),
   lightParticles: ArrayIO( LightParticle.LightParticleIO ),
@@ -85,7 +87,7 @@ export default class ParticleSystem extends PhetioObject {
   // Number of heavy particles inside the container.
   public readonly numberOfHeavyParticlesProperty: NumberProperty;
 
-  //Number of light particles inside the container.
+  // Number of light particles inside the container.
   public readonly numberOfLightParticlesProperty: NumberProperty;
 
   // N, the total number of particles in the container.
@@ -389,7 +391,7 @@ export default class ParticleSystem extends PhetioObject {
   }
 
   /**
-   * Serializes an instance of ParticleSystem.
+   * Serializes this instance of ParticleSystem.
    */
   private toStateObject(): ParticleSystemStateObject {
     return {
@@ -427,7 +429,11 @@ export default class ParticleSystem extends PhetioObject {
     } );
   }
 
-  public static readonly ParticleSystemIO = new IOType<ParticleSystem, ParticleSystemStateObject>( 'ParticleSystemIO', {
+  /**
+   * ParticleSystemIO handles serialization of the particle arrays.
+   * TODO https://github.com/phetsims/gas-properties/issues/231 What type of serialization is this?
+   */
+  private static readonly ParticleSystemIO = new IOType<ParticleSystem, ParticleSystemStateObject>( 'ParticleSystemIO', {
     valueType: ParticleSystem,
     defaultDeserializationMethod: 'applyState',
     stateSchema: PARTICLE_SYSTEM_STATE_SCHEMA,

js/diffusion/model/DiffusionModel.ts

@@ -46,11 +46,13 @@ const CENTER_OF_MASS_PROPERTY_OPTIONS = {
 // Options to createParticle functions
 type CreateParticleOptions = PickRequired<ParticleOptions, 'mass' | 'radius'>;
 
+// This should match DIFFUSION_MODEL_STATE_SCHEMA, but with JavaScript types.
 type DiffusionModelStateObject = {
   particles1: DiffusionParticle1StateObject[];
   particles2: DiffusionParticle2StateObject[];
 };
 
+// This should match DiffusionModelStateObject, but with IOTypes.
 const DIFFUSION_MODEL_STATE_SCHEMA = {
   particles1: ArrayIO( DiffusionParticle1.DiffusionParticle1IO ),
   particles2: ArrayIO( DiffusionParticle2.DiffusionParticle2IO )
@@ -314,7 +316,7 @@ export default class DiffusionModel extends BaseModel {
   }
 
   /**
-   * Serializes an instance of DiffusionModel.
+   * Serializes this instance of DiffusionModel.
    */
   private toStateObject(): DiffusionModelStateObject {
     return {
@@ -329,18 +331,21 @@ export default class DiffusionModel extends BaseModel {
   private static applyState( diffusionModel: DiffusionModel, stateObject: DiffusionModelStateObject ): void {
 
     diffusionModel.particles1.length = 0;
-    diffusionModel.particles2.length = 0;
-
     stateObject.particles1.forEach( ( stateObject: DiffusionParticle1StateObject ) => {
       diffusionModel.particles1.push( DiffusionParticle1.DiffusionParticle1IO.fromStateObject( stateObject ) );
     } );
 
+    diffusionModel.particles2.length = 0;
     stateObject.particles2.forEach( ( stateObject: DiffusionParticle2StateObject ) => {
       diffusionModel.particles2.push( DiffusionParticle2.DiffusionParticle2IO.fromStateObject( stateObject ) );
     } );
   }
 
-  public static readonly DiffusionModelIO = new IOType<DiffusionModel, DiffusionModelStateObject>( 'DiffusionModelIO', {
+  /**
+   * DiffusionModelIO handles serialization of the particle arrays.
+   * TODO https://github.com/phetsims/gas-properties/issues/231 What type of serialization is this?
+   */
+  private static readonly DiffusionModelIO = new IOType<DiffusionModel, DiffusionModelStateObject>( 'DiffusionModelIO', {
     valueType: DiffusionModel,
     defaultDeserializationMethod: 'applyState',
     stateSchema: DIFFUSION_MODEL_STATE_SCHEMA,

js/diffusion/model/DiffusionParticle1.ts

@@ -13,7 +13,7 @@ import StrictOmit from '../../../../phet-core/js/types/StrictOmit.js';
 import GasPropertiesColors from '../../common/GasPropertiesColors.js';
 import gasProperties from '../../gasProperties.js';
 import DiffusionParticle, { DiffusionParticleOptions } from './DiffusionParticle.js';
-import Particle, { ParticleStateObject } from '../../common/model/Particle.js';
+import { ParticleStateObject } from '../../common/model/Particle.js';
 import IOType from '../../../../tandem/js/types/IOType.js';
 
 type SelfOptions = EmptySelfOptions;
@@ -48,9 +48,14 @@ export default class DiffusionParticle1 extends DiffusionParticle {
     } );
   }
 
+  /**
+   * DiffusionParticle1IO handles serialization a DiffusionParticle1. It implements 'Data Type Serialization',
+   * as described in https://github.com/phetsims/phet-io/blob/main/doc/phet-io-instrumentation-technical-guide.md#serialization.
+   */
   public static readonly DiffusionParticle1IO = new IOType<DiffusionParticle1, DiffusionParticle1StateObject>( 'DiffusionParticle1IO', {
     valueType: DiffusionParticle1,
-    stateSchema: Particle.STATE_SCHEMA,
+    stateSchema: DiffusionParticle1.STATE_SCHEMA,
+    // toStateObject: Use the default, which is derived from stateSchema.
     fromStateObject: DiffusionParticle1.fromStateObject
   } );
 }

js/diffusion/model/DiffusionParticle2.ts

@@ -13,7 +13,7 @@ import StrictOmit from '../../../../phet-core/js/types/StrictOmit.js';
 import GasPropertiesColors from '../../common/GasPropertiesColors.js';
 import gasProperties from '../../gasProperties.js';
 import DiffusionParticle, { DiffusionParticleOptions } from './DiffusionParticle.js';
-import Particle, { ParticleStateObject } from '../../common/model/Particle.js';
+import { ParticleStateObject } from '../../common/model/Particle.js';
 import IOType from '../../../../tandem/js/types/IOType.js';
 
 type SelfOptions = EmptySelfOptions;
@@ -48,9 +48,14 @@ export default class DiffusionParticle2 extends DiffusionParticle {
     } );
   }
 
+  /**
+   * DiffusionParticle2IO handles serialization a DiffusionParticle2. It implements 'Data Type Serialization',
+   * as described in https://github.com/phetsims/phet-io/blob/main/doc/phet-io-instrumentation-technical-guide.md#serialization.
+   */
   public static readonly DiffusionParticle2IO = new IOType<DiffusionParticle2, DiffusionParticle2StateObject>( 'DiffusionParticle2IO', {
     valueType: DiffusionParticle2,
-    stateSchema: Particle.STATE_SCHEMA,
+    stateSchema: DiffusionParticle2.STATE_SCHEMA,
+    // toStateObject: Use the default, which is derived from stateSchema.
     fromStateObject: DiffusionParticle2.fromStateObject
   } );
 }