From f514f9fe329a1968ab8cd5ba1893013fe7184e80 Mon Sep 17 00:00:00 2001
From: chrisklus <christopher.klusendorf@colorado.edu>
Date: Wed, 14 Nov 2018 11:26:48 -0700
Subject: [PATCH] Factored out component property link and added to ComboBox,
 see https://github.com/phetsims/sun/issues/405

---
 js/PhetioObject.js | 45 ++++++++++++++++++++++++++++++---------------
 1 file changed, 30 insertions(+), 15 deletions(-)

diff --git a/js/PhetioObject.js b/js/PhetioObject.js
index 7862ddfa..fe8eabfa 100644
--- a/js/PhetioObject.js
+++ b/js/PhetioObject.js
@@ -9,6 +9,7 @@ define( function( require ) {
   'use strict';
 
   // modules
+  var escapeHTML = require( 'PHET_CORE/escapeHTML' );
   var inherit = require( 'PHET_CORE/inherit' );
   var ObjectIO = require( 'TANDEM/types/ObjectIO' );
   var Tandem = require( 'TANDEM/Tandem' );
@@ -27,21 +28,22 @@ define( function( require ) {
   var EMPTY_OBJECT = {};
 
   var DEFAULTS = {
-    tandem: Tandem.optional,      // By default tandems are optional, but subtypes can specify this as
-                                  // `Tandem.tandemRequired` to enforce its presence
-    phetioType: ObjectIO,         // Supply the appropriate IO type
-    phetioDocumentation: null,    // Useful notes about an instrumented instance, shown in the PhET-iO Studio Wrapper
-
-    phetioState: true,            // When true, includes the instance in the PhET-iO state
-    phetioReadOnly: false,        // When true, you can only get values from the instance; no setting allowed.
-    phetioEventType: 'model',     // Default event type for this instance, can be overridden in phetioStartEvent options
-    phetioHighFrequency: false,   // This instance emits events that are high frequency events such as mouse moves or
-                                  // stepSimulation can be omitted from data stream
-    phetioPlayback: false,        // This instance emits events that are needed for data streams intended for playback.
-                                  // See `handlePlaybackEvent.js` for wrapper-side event playback usage.
-    phetioStudioControl: true,    // By default, Studio creates controls for many types of instances.  This option
-                                  // can be set to false to direct Studio to omit the control for the instance.
-    phetioComponentOptions: null  // For propagating phetio options to sub-components, see SUPPORTED_PHET_IO_COMPONENT_OPTIONS
+    tandem: Tandem.optional,        // By default tandems are optional, but subtypes can specify this as
+                                    // `Tandem.tandemRequired` to enforce its presence
+    phetioType: ObjectIO,           // Supply the appropriate IO type
+    phetioDocumentation: null,      // Useful notes about an instrumented instance, shown in the PhET-iO Studio Wrapper
+    phetioState: true,              // When true, includes the instance in the PhET-iO state
+    phetioReadOnly: false,          // When true, you can only get values from the instance; no setting allowed.
+    phetioEventType: 'model',       // Default event type for this instance, can be overridden in phetioStartEvent options
+    phetioHighFrequency: false,     // This instance emits events that are high frequency events such as mouse moves or
+                                    // stepSimulation can be omitted from data stream
+    phetioPlayback: false,          // This instance emits events that are needed for data streams intended for playback.
+                                    // See `handlePlaybackEvent.js` for wrapper-side event playback usage.
+    phetioStudioControl: true,      // By default, Studio creates controls for many types of instances.  This option
+                                    // can be set to false to direct Studio to omit the control for the instance.
+    phetioComponentOptions: null,   // For propagating phetio options to sub-components, see SUPPORTED_PHET_IO_COMPONENT_OPTIONS
+    phetioControlledProperty: null  // A common pattern for a UI component is to control a Property. This option makes
+                                    // sure both are instrumented and augments the component documentation accordingly.
   };
 
   var SUPPORTED_PHET_IO_COMPONENT_OPTIONS = [
@@ -175,6 +177,19 @@ define( function( require ) {
       this.phetioStudioControl = options.phetioStudioControl;
       this.phetioComponentOptions = options.phetioComponentOptions || EMPTY_OBJECT;
 
+      if ( options.phetioControlledProperty ) {
+
+        // If either one is instrumented, then the other must be too.
+        assert && Tandem.validationEnabled() && assert( this.isPhetioInstrumented() === options.phetioControlledProperty.isPhetioInstrumented(),
+          'Property must be instrumented if controlling component is.' );
+
+        // (phet-io) document the instrumented Property that this Checkbox manipulates
+        this.phetioDocumentation +=
+          ` Controls the ${escapeHTML( options.phetioControlledProperty.phetioType.typeName )}: 
+        <a href="#${phetio.PhetioIDUtils.getDOMElementID( options.phetioControlledProperty.tandem.phetioID )}">
+        ${options.phetioControlledProperty.tandem.phetioID}</a>`.trim(); // eliminate preceding whitespace, if any.
+      }
+
       // validate phetioComponentOptions
       assert && _.keys( this.phetioComponentOptions ).forEach( option => {
         assert && assert( SUPPORTED_PHET_IO_COMPONENT_OPTIONS.indexOf( option ) >= 0, 'Unsupported phetioComponentOptions: ' + option );