         invalidate(SIZE);
     }
 
+    /**
+     * Invalidates <code>SIZE</code> and calls draw immediately.  This is
+     * necessary when a parent BaseDisplay is already drawing in response to
+     * an invalidation, as invalidations aren't re-entrant.
+     */
     public function forceRedraw():void
     {
         invalidate(SIZE);
         draw();
     }
 
+    /**
+     * Called when any aspect of the BaseDisplay is marked as invalid.
+     * Subclasses should override this with code to update the display and
+     * validate all identifiers.  The base implementation does nothing.
+     */
+    protected function draw():void
+    {
+    }
+
+    /**
+     * Returns the width as calculated by Flash Player.
+     */
     protected function getDisplayWidth():Number
     {
         return super.width;
     }
 
+    /**
+     * Returns the height as calculated by Flash Player.
+     */
     protected function getDisplayHeight():Number
     {
         return super.height;
     }
 
+    /**
+     * Convenience method to set the size on a child DisplayObject.  This
+     * also detects whether the DisplayObject is a BaseDisplay, and if so,
+     * forces it to redraw.
+     */
     protected function setSizeOn(object:DisplayObject, w:Number, h:Number):void
     {
         var asBaseDisplay:BaseDisplay = object as BaseDisplay;

        addEventListener(Event.REMOVED_FROM_STAGE, _onRemovedFromStage, false, 0, true);
    }

    public override function get width():Number
    {
        return _width;


    private var invalidTokens:Object;

    /**
     * Constructor.
     *
     * @param initialWidth   The initial value for width.
     * @param initialHeight  The initial value for height.
     */
    public function BaseDisplay(initialWidth:Number = 0, initialHeight:Number = 0)
    {
        invalidTokens = { };
