mixin => mixInto() and trait (with added assertions). See #700

doc/index.html

@@ -1058,7 +1058,7 @@ <h4 id="display-backgroundColor">display.backgroundColor</h4>
     <h3 id="paintable" class="section">Paintable</h3>
 
     <p>
-      A mix-in for <a href="#node">Node</a> subtypes that can be filled and/or stroked with a color/gradient/pattern.
+      A trait for <a href="#node">Node</a> subtypes that can be filled and/or stroked with a color/gradient/pattern.
     </p>
 
     <h4 id="paintable-fill">fill</h4>
@@ -1352,7 +1352,7 @@ <h4 id="paintable-cachedPaints">cachedPaints</h4>
     <h3 id="path" class="section">Path</h3>
 
     <p>
-      Path is a <a href="#node">Node</a> subtype that includes the <a href="#paintable">Paintable</a> mixin.
+      Path is a <a href="#node">Node</a> subtype that includes the <a href="#paintable">Paintable</a> trait.
       The main displayed behavior is controlled by its single
       additional option <a href="#path-shape">shape</a> along with the <a href="#paintable-fill">fill</a>
       and <a href="#paintable-stroke">stroke</a> options.

js/accessibility/Accessibility.js

@@ -126,6 +126,7 @@ define( function( require ) {
      * @param {function} type - the constructor for Node
      */
     compose: function( type ) {
+      // Can't avoid circular dependency, so no assertion here. Ensure that 'type' is the constructor for Node.
       var proto = type.prototype;
 
       /**

js/accessibility/AccessibleInstance.js

@@ -414,7 +414,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( AccessibleInstance, {
+  Poolable.mixInto( AccessibleInstance, {
     constructorDuplicateFactory: function( pool ) {
       return function( parent, display, trail ) {
         if ( pool.length ) {

js/accessibility/AccessiblePeer.js

@@ -48,7 +48,7 @@ define( function( require ) {
       options = _.extend( {
         parentContainerElement: null, // a parent container for this peer and potential siblings
         childContainerElement: null, // an child container element where nested elements can be placed
-        labelElement: null, // the element containing this node's label content 
+        labelElement: null, // the element containing this node's label content
         descriptionElement: null // the element that will contain this node's description content
       }, options );
 
@@ -149,7 +149,7 @@ define( function( require ) {
     /**
      * Get an element on this node, looked up by the association flag passed in.
      * @public (scenery-internal)
-     * 
+     *
      * @param  {string} association - see AccessibilityUtil for valid associations
      * @return {HTMLElement}
      */
@@ -168,7 +168,7 @@ define( function( require ) {
       else if ( association === AccessiblePeer.PARENT_CONTAINER ) {
         htmlElement = this.parentContainerElement;
       }
-      
+
       return htmlElement;
     },
 
@@ -190,10 +190,10 @@ define( function( require ) {
 
   // TODO: evaluate pooling, and is it OK to pool only some peers?
   AccessiblePeer.Poolable = {
-    mixin: function( selfDrawableType ) {
+    mixInto: function( selfDrawableType ) {
       // for pooling, allow <AccessiblePeerType>.createFromPool( accessibleInstance ) and accessiblePeer.freeToPool().
       // Creation will initialize the peer to an initial state.
-      Poolable.mixin( selfDrawableType, {
+      Poolable.mixInto( selfDrawableType, {
         defaultFactory: function() {
           return new selfDrawableType();
         },

js/display/BackboneDrawable.js

@@ -447,7 +447,7 @@ define( function( require ) {
     return element;
   };
 
-  Poolable.mixin( BackboneDrawable, {
+  Poolable.mixInto( BackboneDrawable, {
     constructorDuplicateFactory: function( pool ) {
       return function( display, backboneInstance, transformRootInstance, renderer, isDisplayRoot ) {
         if ( pool.length ) {

js/display/CanvasBlock.js

@@ -430,7 +430,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( CanvasBlock, {
+  Poolable.mixInto( CanvasBlock, {
     constructorDuplicateFactory: function( pool ) {
       return function( display, renderer, transformRootInstance, filterRootInstance ) {
         if ( pool.length ) {

js/display/CanvasSelfDrawable.js

@@ -118,11 +118,11 @@ define( function( require ) {
 
     // include stubs (stateless) for marking dirty stroke and fill (if necessary). we only want one dirty flag, not multiple ones, for Canvas (for now)
     if ( usesPaint ) {
-      PaintableStatelessDrawable.mixin( type );
+      PaintableStatelessDrawable.mixInto( type );
     }
 
     // set up pooling
-    SelfDrawable.Poolable.mixin( type );
+    SelfDrawable.Poolable.mixInto( type );
 
     if ( options.dirtyMethods ) {
       for ( var i = 0; i < options.dirtyMethods.length; i++ ) {

js/display/ChangeInterval.js

@@ -155,7 +155,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( ChangeInterval, {
+  Poolable.mixInto( ChangeInterval, {
     constructorDuplicateFactory: function( pool ) {
       return function( drawableBefore, drawableAfter ) {
         if ( pool.length ) {

js/display/DOMBlock.js

@@ -75,7 +75,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( DOMBlock, {
+  Poolable.mixInto( DOMBlock, {
     constructorDuplicateFactory: function( pool ) {
       return function( display, domDrawable ) {
         if ( pool.length ) {

js/display/Instance.js

@@ -1632,7 +1632,7 @@ define( function( require ) {
   } );
 
   // object pooling
-  Poolable.mixin( Instance, {
+  Poolable.mixInto( Instance, {
     constructorDuplicateFactory: function( pool ) {
       return function( display, trail, isDisplayRoot, isSharedCanvasCacheRoot ) {
         if ( pool.length ) {

js/display/PaintSVGState.js

@@ -1,7 +1,7 @@
 // Copyright 2013-2016, University of Colorado Boulder
 
 /**
- * Handles SVG <defs> and fill/stroke style for SVG elements (by composition, not a mix-in or for inheritance).
+ * Handles SVG <defs> and fill/stroke style for SVG elements (by composition, not a trait or for inheritance).
  *
  * @author Jonathan Olson <[email protected]>
  */

js/display/SVGBlock.js

@@ -297,7 +297,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( SVGBlock, {
+  Poolable.mixInto( SVGBlock, {
     constructorDuplicateFactory: function( pool ) {
       return function( display, renderer, transformRootInstance, filterRootInstance ) {
         if ( pool.length ) {

js/display/SVGGradientStop.js

@@ -195,7 +195,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( SVGGradientStop, {
+  Poolable.mixInto( SVGGradientStop, {
     constructorDuplicateFactory: function( pool ) {
       return function( svgGradient, ratio, color ) {
         if ( pool.length ) {

js/display/SVGGroup.js

@@ -416,7 +416,7 @@ define( function( require ) {
     }
   };
 
-  Poolable.mixin( SVGGroup, {
+  Poolable.mixInto( SVGGroup, {
     constructorDuplicateFactory: function( pool ) {
       return function( block, instance, parent ) {
         if ( pool.length ) {

js/display/SVGLinearGradient.js

@@ -77,7 +77,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( SVGLinearGradient, {
+  Poolable.mixInto( SVGLinearGradient, {
     constructorDuplicateFactory: function( pool ) {
       return function( svgBlock, linearGradient ) {
         if ( pool.length ) {

js/display/SVGPattern.js

@@ -93,7 +93,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( SVGPattern, {
+  Poolable.mixInto( SVGPattern, {
     constructorDuplicateFactory: function( pool ) {
       return function( pattern ) {
         if ( pool.length ) {

js/display/SVGRadialGradient.js

@@ -67,7 +67,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( SVGRadialGradient, {
+  Poolable.mixInto( SVGRadialGradient, {
     constructorDuplicateFactory: function( pool ) {
       return function( svgBlock, radialGradient ) {
         if ( pool.length ) {

js/display/SVGSelfDrawable.js

@@ -42,7 +42,7 @@ define( function( require ) {
       this.svgElement = null; // should be filled in by subtype
       this.svgBlock = null; // will be updated by updateSVGBlock()
 
-      this.initializeState( renderer, instance ); // assumes we have a state mixin
+      this.initializeState( renderer, instance ); // assumes we have a state trait
 
       if ( this.usesPaint ) {
         if ( !this.paintState ) {

js/display/SelfDrawable.js

@@ -12,6 +12,7 @@ define( function( require ) {
 
   var Drawable = require( 'SCENERY/display/Drawable' );
   var inherit = require( 'PHET_CORE/inherit' );
+  var inheritance = require( 'PHET_CORE/inheritance' );
   var Poolable = require( 'PHET_CORE/Poolable' );
   var scenery = require( 'SCENERY/scenery' );
 
@@ -71,9 +72,11 @@ define( function( require ) {
   } );
 
   SelfDrawable.Poolable = {
-    mixin: function( selfDrawableType ) {
+    mixInto: function( selfDrawableType ) {
+      assert && assert( _.includes( inheritance( selfDrawableType ), SelfDrawable ) );
+
       // for pooling, allow <SelfDrawableType>.createFromPool( renderer, instance ) and drawable.freeToPool(). Creation will initialize the drawable to an initial state
-      Poolable.mixin( selfDrawableType, {
+      Poolable.mixInto( selfDrawableType, {
         defaultFactory: function() {
           return new selfDrawableType();
         },

js/display/WebGLBlock.js

@@ -873,7 +873,7 @@ define( function( require ) {
     }
   } );
 
-  Poolable.mixin( WebGLBlock, {
+  Poolable.mixInto( WebGLBlock, {
     constructorDuplicateFactory: function( pool ) {
       return function( display, renderer, transformRootInstance, filterRootInstance ) {
         if ( pool.length ) {

js/display/drawables/CanvasNodeDrawable.js

@@ -36,7 +36,7 @@ define( function( require ) {
   inherit( CanvasSelfDrawable, CanvasNodeDrawable, {
     /**
      * Initializes this drawable, starting its "lifetime" until it is disposed. This lifecycle can happen multiple
-     * times, with instances generally created by the SelfDrawable.Poolable mixin (dirtyFromPool/createFromPool), and
+     * times, with instances generally created by the SelfDrawable.Poolable trait (dirtyFromPool/createFromPool), and
      * disposal will return this drawable to the pool.
      * @public (scenery-internal)
      *
@@ -92,7 +92,7 @@ define( function( require ) {
 
   // This sets up CanvasNodeDrawable.createFromPool/dirtyFromPool and drawable.freeToPool() for the type, so
   // that we can avoid allocations by reusing previously-used drawables.
-  SelfDrawable.Poolable.mixin( CanvasNodeDrawable );
+  SelfDrawable.Poolable.mixInto( CanvasNodeDrawable );
 
   return CanvasNodeDrawable;
 } );

js/display/drawables/CircleCanvasDrawable.js

@@ -36,7 +36,7 @@ define( function( require ) {
   inherit( CanvasSelfDrawable, CircleCanvasDrawable, {
     /**
      * Initializes this drawable, starting its "lifetime" until it is disposed. This lifecycle can happen multiple
-     * times, with instances generally created by the SelfDrawable.Poolable mixin (dirtyFromPool/createFromPool), and
+     * times, with instances generally created by the SelfDrawable.Poolable trait (dirtyFromPool/createFromPool), and
      * disposal will return this drawable to the pool.
      * @public (scenery-internal)
      *
@@ -104,12 +104,12 @@ define( function( require ) {
     }
   } );
 
-  // Since we're not using Circle's stateful mixin, we'll need to mix in the Paintable mixin here (of the stateless variety).
-  PaintableStatelessDrawable.mixin( CircleCanvasDrawable );
+  // Since we're not using Circle's stateful trait, we'll need to mix in the Paintable trait here (of the stateless variety).
+  PaintableStatelessDrawable.mixInto( CircleCanvasDrawable );
 
   // This sets up CircleCanvasDrawable.createFromPool/dirtyFromPool and drawable.freeToPool() for the type, so
   // that we can avoid allocations by reusing previously-used drawables.
-  SelfDrawable.Poolable.mixin( CircleCanvasDrawable );
+  SelfDrawable.Poolable.mixInto( CircleCanvasDrawable );
 
   return CircleCanvasDrawable;
 } );

js/display/drawables/CircleDOMDrawable.js

@@ -43,7 +43,7 @@ define( function( require ) {
   inherit( DOMSelfDrawable, CircleDOMDrawable, {
     /**
      * Initializes this drawable, starting its "lifetime" until it is disposed. This lifecycle can happen multiple
-     * times, with instances generally created by the SelfDrawable.Poolable mixin (dirtyFromPool/createFromPool), and
+     * times, with instances generally created by the SelfDrawable.Poolable trait (dirtyFromPool/createFromPool), and
      * disposal will return this drawable to the pool.
      * @public (scenery-internal)
      *
@@ -58,7 +58,7 @@ define( function( require ) {
       // Super-type initialization
       this.initializeDOMSelfDrawable( renderer, instance );
 
-      // Stateful mix-in initialization
+      // Stateful trait initialization
       this.initializeState( renderer, instance );
 
       // @protected {Matrix3} - We need to store an independent matrix, as our CSS transform actually depends on the radius.
@@ -186,12 +186,12 @@ define( function( require ) {
     }
   } );
 
-  // Include Circle's stateful mixin (used for dirty flags)
-  CircleStatefulDrawable.mixin( CircleDOMDrawable );
+  // Include Circle's stateful trait (used for dirty flags)
+  CircleStatefulDrawable.mixInto( CircleDOMDrawable );
 
   // This sets up CircleDOMDrawable.createFromPool/dirtyFromPool and drawable.freeToPool() for the type, so
   // that we can avoid allocations by reusing previously-used drawables.
-  SelfDrawable.Poolable.mixin( CircleDOMDrawable );
+  SelfDrawable.Poolable.mixInto( CircleDOMDrawable );
 
   return CircleDOMDrawable;
 } );

js/display/drawables/CircleSVGDrawable.js

@@ -40,7 +40,7 @@ define( function( require ) {
   inherit( SVGSelfDrawable, CircleSVGDrawable, {
     /**
      * Initializes this drawable, starting its "lifetime" until it is disposed. This lifecycle can happen multiple
-     * times, with instances generally created by the SelfDrawable.Poolable mixin (dirtyFromPool/createFromPool), and
+     * times, with instances generally created by the SelfDrawable.Poolable trait (dirtyFromPool/createFromPool), and
      * disposal will return this drawable to the pool.
      * @public (scenery-internal)
      *
@@ -79,12 +79,12 @@ define( function( require ) {
     }
   } );
 
-  // Include Circle's stateful mixin (used for dirty flags)
-  CircleStatefulDrawable.mixin( CircleSVGDrawable );
+  // Include Circle's stateful trait (used for dirty flags)
+  CircleStatefulDrawable.mixInto( CircleSVGDrawable );
 
   // This sets up CircleSVGDrawable.createFromPool/dirtyFromPool and drawable.freeToPool() for the type, so
   // that we can avoid allocations by reusing previously-used drawables.
-  SelfDrawable.Poolable.mixin( CircleSVGDrawable );
+  SelfDrawable.Poolable.mixInto( CircleSVGDrawable );
 
   return CircleSVGDrawable;
 } );

js/display/drawables/CircleStatefulDrawable.js

@@ -1,21 +1,23 @@
 // Copyright 2016, University of Colorado Boulder
 
 /**
- * A mixin to drawables for Circle that need to store state about what the current display is currently showing,
+ * A trait for drawables for Circle that need to store state about what the current display is currently showing,
  * so that updates to the Circle will only be made on attributes that specifically changed (and no change will be
  * necessary for an attribute that changed back to its original/currently-displayed value). Generally, this is used
  * for DOM and SVG drawables.
  *
- * This mixin assumes the PaintableStateful mixin is also mixed (always the case for Circle stateful drawables).
+ * This trait assumes the PaintableStateful trait is also mixed (always the case for Circle stateful drawables).
  *
  * @author Jonathan Olson <[email protected]>
  */
 
 define( function( require ) {
   'use strict';
 
+  var inheritance = require( 'PHET_CORE/inheritance' );
   var PaintableStatefulDrawable = require( 'SCENERY/display/drawables/PaintableStatefulDrawable' );
   var scenery = require( 'SCENERY/scenery' );
+  var SelfDrawable = require( 'SCENERY/display/SelfDrawable' );
 
   var CircleStatefulDrawable = {
     /**
@@ -32,11 +34,13 @@ define( function( require ) {
      *
      * @param {function} drawableType - The constructor for the drawable type
      */
-    mixin: function( drawableType ) {
+    mixInto: function( drawableType ) {
+      assert && assert( _.includes( inheritance( drawableType ), SelfDrawable ) );
+
       var proto = drawableType.prototype;
 
       /**
-       * Initializes the stateful mixin state, starting its "lifetime" until it is disposed with disposeState().
+       * Initializes the stateful trait state, starting its "lifetime" until it is disposed with disposeState().
        * @protected
        *
        * @param {number} renderer - Renderer bitmask, see Renderer's documentation for more details.
@@ -58,7 +62,7 @@ define( function( require ) {
       };
 
       /**
-       * Disposes the stateful mixin state, so it can be put into the pool to be initialized again.
+       * Disposes the stateful trait state, so it can be put into the pool to be initialized again.
        * @protected
        */
       proto.disposeState = function() {
@@ -96,7 +100,7 @@ define( function( require ) {
         this.dirtyRadius = false;
       };
 
-      PaintableStatefulDrawable.mixin( drawableType );
+      PaintableStatefulDrawable.mixInto( drawableType );
     }
   };