From c0ce1c1979dd52f7f08bbaba0a4bda9b65177d7c Mon Sep 17 00:00:00 2001
From: pixelzoom <cmalley@pixelzoom.com>
Date: Fri, 10 Mar 2023 17:27:18 -0700
Subject: [PATCH] add doc to explain why we're opt-ing out of iO
 instrumentation, or not instrumenting

---
 js/common/view/CurveManipulationIconNode.ts | 6 +++---
 js/common/view/GraphsNode.ts                | 2 ++
 js/common/view/LabeledLinesNode.ts          | 6 ++++--
 js/common/view/LabeledPointsNode.ts         | 5 ++++-
 4 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/js/common/view/CurveManipulationIconNode.ts b/js/common/view/CurveManipulationIconNode.ts
index 5a917357..a253cc40 100644
--- a/js/common/view/CurveManipulationIconNode.ts
+++ b/js/common/view/CurveManipulationIconNode.ts
@@ -26,7 +26,7 @@ const CHART_TRANSFORM_OPTIONS = {
 const TRANSFORMED_CURVE_OPTIONS = {
   numberOfPoints: 70,
   xRange: CalculusGrapherConstants.CURVE_X_RANGE,
-  tandem: Tandem.OPT_OUT
+  tandem: Tandem.OPT_OUT // curves for icons are not instrumented
 };
 
 export default class CurveManipulationIconNode extends Node {
@@ -86,7 +86,7 @@ export default class CurveManipulationIconNode extends Node {
     // Create the solid curve node.
     const solidCurveNode = new CurveNode( solidCurve, chartTransform, {
       stroke: stroke,
-      tandem: Tandem.OPT_OUT
+      tandem: Tandem.OPT_OUT // CurveNodes for icons are not instrumented
     } );
 
     const children = [ chartRectangle, solidCurveNode ];
@@ -99,7 +99,7 @@ export default class CurveManipulationIconNode extends Node {
           lineDash: [ 4.5, 2 ],
           lineWidth: 1
         },
-        tandem: Tandem.OPT_OUT
+        tandem: Tandem.OPT_OUT // CurveNodes for icons are not instrumented
       } );
       children.push( dashedCurveNode );
     }
diff --git a/js/common/view/GraphsNode.ts b/js/common/view/GraphsNode.ts
index 1a0dd375..46cc909f 100644
--- a/js/common/view/GraphsNode.ts
+++ b/js/common/view/GraphsNode.ts
@@ -117,6 +117,8 @@ export default class GraphsNode extends Node {
 
     this.graphSetNode = new Node();
 
+    // graphSetsAnimator is only PhET-iO instrumented if we have more than one GraphSet. If there is only one
+    // graphSet, then it exists to put that GraphSet in its correct position, and then it never changes.
     this.graphSetsAnimator = new GraphSetsAnimator(
       ( model.graphSets.length > 1 ) ? options.tandem.createTandem( 'graphSetsAnimator' ) : Tandem.OPT_OUT );
 
diff --git a/js/common/view/LabeledLinesNode.ts b/js/common/view/LabeledLinesNode.ts
index b14533eb..92c83ae6 100644
--- a/js/common/view/LabeledLinesNode.ts
+++ b/js/common/view/LabeledLinesNode.ts
@@ -38,8 +38,10 @@ export default class LabeledLinesNode extends Node {
       phetioVisiblePropertyInstrumented: false
     }, providedOptions );
 
-    // LabeledLineNode instances.
-    const labeledLineNodes = labeledLines.map( labeledLine => new LabeledLineNode( labeledLine, chartTransform, options.labeledLineOptions ) );
+    // LabeledLineNode instances are not instrumented. The entire PhET-iO API lives in the model.
+    // See model.tools.labeledLines and https://github.com/phetsims/calculus-grapher/issues/198
+    const labeledLineNodes = labeledLines.map( labeledLine =>
+      new LabeledLineNode( labeledLine, chartTransform, options.labeledLineOptions ) );
 
     options.children = labeledLineNodes;
 
diff --git a/js/common/view/LabeledPointsNode.ts b/js/common/view/LabeledPointsNode.ts
index ce51581a..a788b3d4 100644
--- a/js/common/view/LabeledPointsNode.ts
+++ b/js/common/view/LabeledPointsNode.ts
@@ -29,7 +29,10 @@ export default class LabeledPointsNode extends Node {
     // LabeledPointNode instances
     const labeledPointNodes = labeledPoints.map( labeledPoint =>
       new LabeledPointNode( labeledPoint, chartTransform, predictEnabledProperty, curveLayerVisibleProperty, {
-        tandem: Tandem.OPT_OUT // see https://github.com/phetsims/calculus-grapher/issues/198
+
+        // LabeledPointNode instances are not instrumented. The entire PhET-iO API lives in the model.
+        // See model.tools.labeledPoints and https://github.com/phetsims/calculus-grapher/issues/198
+        tandem: Tandem.OPT_OUT
       } ) );
 
     super( {