phetsims / projectile-data-lab

"Projectile Data Lab" is an educational simulation in HTML5, by PhET Interactive Simulations.
GNU General Public License v3.0
0 stars 0 forks source link

More documentation about how DynamicProperty is used. #226

Closed pixelzoom closed 5 months ago

pixelzoom commented 5 months ago

For code review #32 ... @samreid @matthew-blackman and I discussed this on Zoom.

This sim has a nice pattern that leverages DynamicProperty, and I was briefed on this pattern during our "code review kickoff" meeting. But in reviewing the documentation in the code and implementation-notes.md, it feels like this pattern is a bit underdocumented -- I'm not sure I would have gotten up to speed as quickly without the kick-off meeting. Since it's key to understanding how the model works, it would be worth adding some more documentation, possibly with an example based on a specific DynamicProperty.

I'll leave it up to @samreid and @matthew-blackman to decide how to best do this. I'll be happy to review if you'd like.

samreid commented 5 months ago

I added documentation in the implementation-notes.md, and at usage sites like:

  //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  // These values are DynamicProperties that are determined by the Launcher, see Launcher.ts and implementation-notes.md

  // Specifies the average speed of launched projectiles
  private readonly meanSpeedProperty: TReadOnlyProperty<number>;

  // Specifies the speed standard deviation for launched projectiles.
  private readonly standardDeviationSpeedProperty: TReadOnlyProperty<number>;

  // Indicates the current value for the standard deviation of the angle of launch.
  public readonly standardDeviationAngleProperty: TReadOnlyProperty<number>;

  // Indicates the current value for the angle stabilizer.
  public readonly angleStabilizerProperty: DynamicProperty<number, number, Launcher>;

  // End of DynamicProperties
  //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

Other changes were done in https://github.com/phetsims/projectile-data-lab/issues/222, closing.