docs related to review, see #105

js/AllLevelsCompletedNode.ts

@@ -37,6 +37,8 @@ export default class AllLevelsCompletedNode extends Node {
     super();
 
     const options = optionize<AllLevelsCompletedNodeOptions, SelfOptions, NodeOptions>()( {
+
+      // SelfOptions
       faceDiameter: 160,
       maxTextWidth: 300
     }, providedOptions );

js/ElapsedTimeNode.ts

@@ -51,7 +51,7 @@ export default class ElapsedTimeNode extends HBox {
 
     super( options );
 
-    // Update the time display
+    // Update the time display.
     const elapsedTimeListener = ( elapsedTime: number ) => {
       timeValue.text = GameTimer.formatTime( elapsedTime );
     };

js/FiniteStatusBar.ts

@@ -25,6 +25,7 @@ import Bounds2 from '../../dot/js/Bounds2.js';
 
 // Valid values for scoreDisplayConstructor. These are the types that are relevant for this status bar.
 // All constructors must have the same signature!
+// REVIEW-TS: Would it be possible to type this and thus enforce the requirement for having the same signature?
 const VALID_SCORE_DISPLAY_CONSTRUCTORS = [
   ScoreDisplayLabeledNumber, ScoreDisplayLabeledStars
 ];
@@ -54,7 +55,7 @@ type SelfOptions = {
   startOverButtonOptions?: TextPushButtonOptions | null;
   startOverButtonText?: string;
 
-  // Timer
+  // options for the timer node
   clockIconRadius?: number;
 
   // spacing and margin for things in the bar

js/InfiniteStatusBar.ts

@@ -22,6 +22,7 @@ import { PushButtonListener } from '../../sun/js/buttons/PushButtonModel.js';
 
 // Valid values for scoreDisplayConstructor. These are the types that are relevant for this status bar.
 // All constructors must have the same signature!
+// REVIEW-TS: Would it be possible to type this and thus enforce the requirement for having the same signature?
 const VALID_SCORE_DISPLAY_CONSTRUCTORS = [
   ScoreDisplayLabeledNumber, ScoreDisplayNumberAndStar
 ];

js/LevelSelectionButton.ts

@@ -32,6 +32,7 @@ import vegas from './vegas.js';
 // constants
 const DEFAULT_BEST_TIME_FONT = new PhetFont( 24 );
 const SCALING_TOLERANCE = 1E-4; // Empirically chosen as something the human eye is unlikely to notice.
+// REVIEW-TS: Would it be possible to type this and thus enforce the requirement for having the same signature?
 const VALID_SCORE_DISPLAY_CONSTRUCTORS = [
 
   // All constructors must have the same signature!

js/RewardNode.ts

@@ -31,7 +31,7 @@ import vegas from './vegas.js';
 const DEBUG_CANVAS_NODE_BOUNDS = false; // shows a gray rectangle for the CanvasNode to help ensure that its bounds are accurate
 const MAX_SPEED = 200; // The maximum speed an image can fall in screen pixels per second.
 
-// Data structure to hold a cached HTMLImageElement and its associated properties
+// Data structure to hold a cached HTMLImageElement and its associated properties.
 type CachedImage = {
 
   // The image to be rendered in the canvas, to be filled in by toImage callback.

js/ScoreDisplayLabeledNumber.ts

@@ -31,6 +31,8 @@ export default class ScoreDisplayLabeledNumber extends Node {
   constructor( scoreProperty: IProperty<number>, providedOptions?: ScoreDisplayLabeledNumberOptions ) {
 
     const options = optionize<ScoreDisplayLabeledNumberOptions, SelfOptions, HBoxOptions>()( {
+
+      // SelfOptions
       font: StatusBar.DEFAULT_FONT,
       textFill: 'black',
       scoreDecimalPlaces: 0

js/ScoreDisplayLabeledStars.ts

@@ -30,6 +30,8 @@ export default class ScoreDisplayLabeledStars extends HBox {
   constructor( scoreProperty: IProperty<number>, providedOptions?: ScoreDisplayLabeledStarsOptions ) {
 
     const options = optionize<ScoreDisplayLabeledStarsOptions, SelfOptions, HBoxOptions>()( {
+
+      // SelfOptions
       font: StatusBar.DEFAULT_FONT,
       textFill: 'black',
       spacing: 5