From efadbf54248c24210934488bc3f110a99c89470b Mon Sep 17 00:00:00 2001
From: Jesse Greenberg <jesse.greenberg@colorado.edu>
Date: Tue, 3 Apr 2018 16:12:36 -0600
Subject: [PATCH 1/2] add JSDoc for AccessibleInstance, see #758

---
 js/accessibility/AccessibleInstance.js | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/js/accessibility/AccessibleInstance.js b/js/accessibility/AccessibleInstance.js
index a0f17897b..636215979 100644
--- a/js/accessibility/AccessibleInstance.js
+++ b/js/accessibility/AccessibleInstance.js
@@ -22,12 +22,13 @@ define( function( require ) {
   var globalId = 1;
 
   /**
+   * Constructor for AccessibleInstance, uses an initialize method for pooling.
+   * 
+   * @param {AccessibleInstance|null} parent - parent of this instance, null if root of AccessibleInstance tree
+   * @param {Display}
+   * @param {Trail} trail - trail to the node for this AccessibleInstance 
    * @constructor
    * @mixes Poolable
-   *
-   * @param parent
-   * @param display
-   * @param trail
    */
   function AccessibleInstance( parent, display, trail ) {
     this.initializeAccessibleInstance( parent, display, trail );
@@ -36,10 +37,13 @@ define( function( require ) {
   scenery.register( 'AccessibleInstance', AccessibleInstance );
 
   inherit( Events, AccessibleInstance, {
+
     /**
-     * @param {AccessibleInstance|null} parent
+     * Initializes an AccessibleInstance, implements construction for pooling.
+     * 
+     * @param {AccessibleInstance|null} parent - null if this AccessibleInstance is root of AccessibleInstance tree
      * @param {Display} display
-     * @param {HTMLElement} [primarySibling] - If not included here, subtype is responsible for setting it in the constructor.
+     * @param {Trail} trail - trail to node for this AccessibleInstance
      * @returns {AccessibleInstance} - Returns 'this' reference, for chaining
      */
     initializeAccessibleInstance: function( parent, display, trail ) {

From 8da69867e825cc5e0d3eb2feb1a76a0beed10e0b Mon Sep 17 00:00:00 2001
From: Jesse Greenberg <jesse.greenberg@colorado.edu>
Date: Tue, 3 Apr 2018 16:41:17 -0600
Subject: [PATCH 2/2] improve documentation in AccessibleInstance, see #758

---
 js/accessibility/AccessibleInstance.js | 38 ++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/js/accessibility/AccessibleInstance.js b/js/accessibility/AccessibleInstance.js
index 636215979..bb0215f71 100644
--- a/js/accessibility/AccessibleInstance.js
+++ b/js/accessibility/AccessibleInstance.js
@@ -143,6 +143,8 @@ define( function( require ) {
     },
 
     /**
+     * Add a subtree of AccessibleInstances to this AccessibleInstance.
+     * 
      * Consider the following example:
      *
      * We have a node structure:
@@ -170,6 +172,10 @@ define( function( require ) {
      *       ABCDE.addSubtree( ABCDEG )
      *     ABC.addSubtree( ABCDF )
      *       ABC.addSubtree( ABCDFH )
+     *
+     * @param {Trail} trail - the AccessibleInstances under the trail's last node will be added as descendants of this
+     *                        AccessibleInstance.
+     * @public (scenery-internal)
      */
     addSubtree: function( trail ) {
       sceneryLog && sceneryLog.AccessibleInstance && sceneryLog.AccessibleInstance(
@@ -197,6 +203,13 @@ define( function( require ) {
       sceneryLog && sceneryLog.AccessibleInstance && sceneryLog.pop();
     },
 
+    /**
+     * Remove a subtree of AccessibleInstances from this AccessibleInstance
+     *
+     * @param {Trail} trail - children of this AccessibleInstance will be removed if the child trails are extensions
+     *                        of the trail.
+     * @public (scenery-internal)
+     */
     removeSubtree: function( trail ) {
       sceneryLog && sceneryLog.AccessibleInstance && sceneryLog.AccessibleInstance(
         'removeSubtree on ' + this.toString() + ' with trail ' + trail.toString() );
@@ -218,7 +231,8 @@ define( function( require ) {
     },
 
     /**
-     * TODO: doc
+     * Mark as unsorted so that the display will sort the subtree of AccessibleInstances under this one.
+     * @public (scenery-internal)
      */
     markAsUnsorted: function() {
       if ( this.isSorted ) {
@@ -266,7 +280,11 @@ define( function( require ) {
 
     /**
      * Sort our child accessible instances in the order they should appear in the parallel DOM. We do this by
-     * creating a comparison function between two accessible instances, and sorting the array with that.
+     * creating a comparison function between two accessible instances. The function walks along the trails
+     * of the children, looking for specified accessible orders that would determine the ordering for the two
+     * AccessibleInstances.
+     * 
+     * @public (scenery-internal)
      */
     sortChildren: function() {
       assert && assert( !this.isSorted, 'No need to sort children if it is already marked as sorted' );
@@ -391,7 +409,11 @@ define( function( require ) {
       }
     },
 
-    // Recursive disposal
+    /**
+     * Recursive disposal, to make eligible for garbage collection.
+     * 
+     * @public (scenery-internal)
+     */
     dispose: function() {
       sceneryLog && sceneryLog.AccessibleInstance && sceneryLog.AccessibleInstance(
         'Disposing ' + this.toString() );
@@ -435,10 +457,20 @@ define( function( require ) {
       sceneryLog && sceneryLog.AccessibleInstance && sceneryLog.pop();
     },
 
+    /**
+     * For debugging purposes.
+     *
+     * @return {string}
+     */
     toString: function() {
       return this.id + '#{' + this.trail.toString() + '}';
     },
 
+    /**
+     * For debugging purposes, inspect the tree of AccessibleInstances from the root.
+     * 
+     * @public (scenery-internal)
+     */
     auditRoot: function() {
       assert && assert( this.trail.length === 0,
         'Should only call auditRoot() on the root AccessibleInstance for a display' );