Adding comments and cleaning up code, see #40

js/common/model/KeplersLawsModel.ts

@@ -2,6 +2,7 @@
 
 /**
  * The model in charge of the Kepler's Laws Screen components.
+ * It extends the SolarSystemCommonModel, and adds the necessary properties and logic to handle the laws functionalities.
  *
  * @author Agustín Vallejo
  */
@@ -34,6 +35,8 @@ export type KeplersLawsModelOptions = SelfOptions & StrictOmit<SuperTypeOptions,
 
 class KeplersLawsModel extends SolarSystemCommonModel<EllipticalOrbitEngine> {
   public readonly selectedLawProperty: EnumerationProperty<LawMode>;
+
+  // Will enforce that the orbit is always circular
   public readonly alwaysCircularProperty = new BooleanProperty( false );
 
   // Booleans to keep track of which law is selected
@@ -61,13 +64,15 @@ class KeplersLawsModel extends SolarSystemCommonModel<EllipticalOrbitEngine> {
   public readonly semiMajorAxisVisibleProperty = new BooleanProperty( false );
   public readonly periodVisibleProperty = new BooleanProperty( true );
 
+  // Graph exponents
   public readonly selectedAxisPowerProperty = new NumberProperty( 1 );
   public readonly selectedPeriodPowerProperty = new NumberProperty( 1 );
 
   public readonly poweredSemiMajorAxisProperty: ReadOnlyProperty<number>;
   public readonly poweredPeriodProperty: ReadOnlyProperty<number>;
 
-  public readonly periodPath: PeriodTracker;
+  // The object that controls the blue path drawn when measuring the period
+  public readonly periodTracker: PeriodTracker;
 
   public constructor( providedOptions: KeplersLawsModelOptions ) {
     const options = optionize<KeplersLawsModelOptions, SelfOptions, SuperTypeOptions>()( {
@@ -88,6 +93,7 @@ class KeplersLawsModel extends SolarSystemCommonModel<EllipticalOrbitEngine> {
     } );
 
     this.bodies[ 0 ].massProperty.lazyLink( () => {
+      // Pause the sim when the Sun's ( id = 0 ) mass is changed
       this.isPlayingProperty.value = false;
     } );
 
@@ -116,8 +122,6 @@ class KeplersLawsModel extends SolarSystemCommonModel<EllipticalOrbitEngine> {
 
     this.axisVisibleProperty.link( axisVisible => {
       this.semiaxisVisibleProperty.value = axisVisible ? this.semiaxisVisibleProperty.value : false;
-      //REVIEW: commented-out code
-      // this.eccentricityVisibleProperty.value = axisVisible ? this.eccentricityVisibleProperty.value : false;
     } );
     this.fociVisibleProperty.link( fociVisible => {
       this.stringsVisibleProperty.value = fociVisible ? this.stringsVisibleProperty.value : false;
@@ -142,11 +146,14 @@ class KeplersLawsModel extends SolarSystemCommonModel<EllipticalOrbitEngine> {
       this.engine.update();
     } );
 
-    this.periodPath = new PeriodTracker( this );
+    this.periodTracker = new PeriodTracker( this );
 
     this.forceScaleProperty.value = 0.5;
   }
 
+  /**
+   * Simpler version of loadBodyStates than the one in SolarSystemCommonModel
+   */
   public override loadBodyStates( bodiesInfo: BodyInfo[] ): void {
     super.loadBodyStates( bodiesInfo );
 
@@ -178,7 +185,7 @@ class KeplersLawsModel extends SolarSystemCommonModel<EllipticalOrbitEngine> {
     this.selectedAxisPowerProperty.reset();
     this.selectedPeriodPowerProperty.reset();
     this.alwaysCircularProperty.reset();
-    this.periodPath.reset();
+    this.periodTracker.reset();
 
     this.visibilityReset();
     this.engine.updateAllowed = true;
@@ -196,7 +203,7 @@ class KeplersLawsModel extends SolarSystemCommonModel<EllipticalOrbitEngine> {
 
   public override step( dt: number ): void {
     super.step( dt );
-    this.periodPath.step( dt );
+    this.periodTracker.step( dt );
   }
 
   /**

js/common/model/OrbitTypes.ts

@@ -13,7 +13,6 @@ export default class OrbitTypes extends EnumerationValue {
   public static readonly STABLE_ORBIT = new OrbitTypes();
   public static readonly ESCAPE_ORBIT = new OrbitTypes();
   public static readonly CRASH_ORBIT = new OrbitTypes();
-  public static readonly TOO_BIG = new OrbitTypes();
 
   public static readonly enumeration = new Enumeration( OrbitTypes, {
     phetioDocumentation: 'The reason this orbit is unstable'

js/common/model/OrbitalArea.ts

@@ -1,6 +1,9 @@
 // Copyright 2023, University of Colorado Boulder
 
 /**
+ *
+ * Class that handles the internal logic of the orbital areas.
+ * It keeps track of the position of the dot in the orbital area, the start and end positions, the angles, the completion, etc.
  *
  * @author Agustín Vallejo
  */
@@ -15,12 +18,11 @@ export default class OrbitalArea {
   public endPosition = Vector2.ZERO; // End position of the orbital area
   public startAngle = 0;
   public endAngle = 0;
-  public completion = 0; // Proportional completion of the orbital area
-  public sweptArea = 0;
+  public completion = 0; // Proportional completion of the orbital area, goes up to 1
+  public sweptArea = 0; // Total area the section will have when completion = 1
   public insideProperty = new BooleanProperty( false );
   public alreadyEntered = false;
-  public active = false;
-  public resetted = true;
+  public active = false; // Whether the shown areas include this one
 
   public constructor( public readonly index: number ) {
     // noop
@@ -37,7 +39,6 @@ export default class OrbitalArea {
     this.insideProperty.reset();
     this.alreadyEntered = false;
     this.active = false;
-    this.resetted = true;
   }
 }
 

js/common/model/PeriodTracker.ts

@@ -1,7 +1,6 @@
 // Copyright 2023, University of Colorado Boulder
 /**
- * Model for the Third Law Screen. Keeps track of the state of the blue line tracking the body
- * when the PeriodTimerNode is set to run.
+ * Keeps track of the state of the blue line tracking the body when the PeriodTimerNode is set to run.
  *
  * @author Agustín Vallejo
  */
@@ -30,13 +29,12 @@ export class TrackingState extends EnumerationValue {
 export default class PeriodTracker {
   public beganPeriodTimerAt = 0;
   public trackingState: TrackingState;
-  public afterPeriodThreshold = false;
+  public afterPeriodThreshold = false; // Whether the body has passed some percentage of the period
   public readonly periodTimer: Stopwatch;
   public readonly fadingTimer: Stopwatch;
   public readonly fadingEmitter = new Emitter();
 
-  // Fraction of the period that the line will be fading
-  public readonly fadingLifetime = 3;
+  public readonly fadingDuration = 3;
 
   public constructor( private readonly model: KeplersLawsModel ) {
     this.trackingState = TrackingState.IDLE;
@@ -49,7 +47,7 @@ export default class PeriodTracker {
     this.fadingTimer = new Stopwatch( {
       position: Vector2.ZERO,
       timePropertyOptions: {
-        range: new Range( 0, this.fadingLifetime )
+        range: new Range( 0, this.fadingDuration )
       }
     } );
 
@@ -63,9 +61,10 @@ export default class PeriodTracker {
       if ( isRunning ) {
         this.trackingState = TrackingState.RUNNING;
         this.beganPeriodTimerAt = this.model.timeProperty.value;
-        this.model.isPlayingProperty.value = true; // TODO This is just true for testing
+        this.model.isPlayingProperty.value = true; // TODO This is only true for testing
       }
       else if ( this.trackingState !== TrackingState.FADING ) {
+        // If the period track is not fading and it's stopped, reset the period timer
         this.reset();
         this.periodTimer.timeProperty.set( 0 );
       }

js/common/view/EllipticalOrbitNode.ts

@@ -251,7 +251,7 @@ export default class EllipticalOrbitNode extends Path {
         [ model.semiaxisVisibleProperty, model.semiMajorAxisVisibleProperty, model.eccentricityVisibleProperty ]
       )
     } );
-    const periodPathNode = new PeriodTrackerNode( model );
+    const periodTrackerNode = new PeriodTrackerNode( model );
 
     // Text Nodes
     labelsLayer.addChild( aLabelNode );
@@ -277,7 +277,7 @@ export default class EllipticalOrbitNode extends Path {
 
     // Third Law: SemiMajor axis, and track
     thirdLawLayer.addChild( semiMajorAxisPath );
-    thirdLawLayer.addChild( periodPathNode );
+    thirdLawLayer.addChild( periodTrackerNode );
 
     this.topLayer.addChild( foci[ 0 ] );
     this.topLayer.addChild( foci[ 1 ] );
@@ -425,15 +425,15 @@ export default class EllipticalOrbitNode extends Path {
       semiMajorAxisPath.shape = new Shape().moveTo( 0, 0 ).lineTo( -radiusX, 0 );
 
       // Period track line
-      periodPathNode.update( scale, center, radiusX, radiusY );
+      periodTrackerNode.update( scale, center, radiusX, radiusY );
     };
 
     this.orbit.changedEmitter.addListener( updatedOrbit );
     this.orbit.ranEmitter.addListener( () => {
       updatedOrbit();
 
-      // Had to call the method here because apparently the listener is created before periodPathNode is instantiated
-      periodPathNode.updateShape();
+      // Had to call the method here because apparently the listener is created before periodTrackerNode is instantiated
+      periodTrackerNode.updateShape();
     } );
 
     this.shapeMultilink = Multilink.multilink(

js/common/view/KeplersLawsScreenView.ts

@@ -168,7 +168,7 @@ class KeplersLawsScreenView extends SolarSystemCommonScreenView {
       }
     );
 
-    this.periodTimerNode = new PeriodTimerNode( model.periodPath.periodTimer, this.modelViewTransformProperty, this.layoutBounds, {
+    this.periodTimerNode = new PeriodTimerNode( model.periodTracker.periodTimer, this.modelViewTransformProperty, this.layoutBounds, {
       dragBoundsProperty: this.visibleBoundsProperty,
       visibleProperty: model.periodVisibleProperty,
       soundViewNode: this

js/common/view/PeriodTrackerNode.ts

@@ -14,7 +14,7 @@ import PeriodTracker, { TrackingState } from '../model/PeriodTracker.js';
 import Vector2 from '../../../../dot/js/Vector2.js';
 
 export default class PeriodTrackerNode extends Path {
-  private periodPath: PeriodTracker;
+  private periodTracker: PeriodTracker;
 
   // Initial values for the ellipse
   public orbitScale = 1;
@@ -31,23 +31,23 @@ export default class PeriodTrackerNode extends Path {
       visibleProperty: model.periodVisibleProperty
     } );
 
-    this.periodPath = model.periodPath;
+    this.periodTracker = model.periodTracker;
 
-    this.periodPath.fadingEmitter.addListener( () => {
+    this.periodTracker.fadingEmitter.addListener( () => {
       this.updateFade();
     } );
 
-    this.periodPath.periodTimer.isRunningProperty.lazyLink( isRunning => {
+    this.periodTracker.periodTimer.isRunningProperty.lazyLink( isRunning => {
       if ( isRunning ) {
         this.model.engine.periodTraceEnd = this.model.engine.periodTraceStart;
         this.updateShape();
       }
     } );
 
     this.model.engine.changedEmitter.addListener( () => {
-      this.periodPath.reset();
-      this.periodPath.periodTimer.timeProperty.set( 0 );
-      this.periodPath.periodTimer.isRunningProperty.value = false;
+      this.periodTracker.reset();
+      this.periodTracker.periodTimer.timeProperty.set( 0 );
+      this.periodTracker.periodTimer.isRunningProperty.value = false;
       this.updateShape();
     } );
 
@@ -63,7 +63,7 @@ export default class PeriodTrackerNode extends Path {
     this.radiusX = radiusX;
     this.radiusY = radiusY;
 
-    if ( this.periodPath.trackingState === TrackingState.RUNNING ) {
+    if ( this.periodTracker.trackingState === TrackingState.RUNNING ) {
       this.updateShape();
     }
   }
@@ -78,7 +78,7 @@ export default class PeriodTrackerNode extends Path {
     const retrograde = this.model.engine.retrograde;
     const angleDiff = this.model.engine.periodTraceEnd - this.model.engine.periodTraceStart;
     const angleThreshold = Math.PI / 10;
-    if ( this.periodPath.afterPeriodThreshold && (
+    if ( this.periodTracker.afterPeriodThreshold && (
       ( retrograde && angleDiff <= angleThreshold ) ||
       ( !retrograde && angleDiff >= 2 * Math.PI - angleThreshold ) ) ) {
       this.shape = new Shape().ellipse( 0, 0, this.radiusX, this.radiusY, 0 );
@@ -87,12 +87,12 @@ export default class PeriodTrackerNode extends Path {
       this.shape = new Shape().ellipticalArc( 0, 0, this.radiusX, this.radiusY, 0, startAngle, endAngle, retrograde );
     }
     this.startCircle.translation = startTracePosition;
-    this.startCircle.visible = startAngle !== endAngle || this.periodPath.periodTimer.isRunningProperty.value;
+    this.startCircle.visible = startAngle !== endAngle || this.periodTracker.periodTimer.isRunningProperty.value;
   }
 
   public updateFade(): void {
     this.shape = new Shape().ellipse( 0, 0, this.radiusX, this.radiusY, 0 );
-    this.opacity = 1 - this.periodPath.fadingTimer.timeProperty.value / this.periodPath.fadingLifetime;
+    this.opacity = 1 - this.periodTracker.fadingTimer.timeProperty.value / this.periodTracker.fadingLifetime;
   }
 }