Documentation improvements.

Removed the superfluous EZEvent.


git-svn-id: svn+ssh://src.earth.threerings.net/vilya/trunk@554 c613c5cb-e716-0410-b11b-feb51c14d237

src/as/com/threerings/ezgame/AbstractControl.as

@@ -28,6 +28,7 @@ import flash.events.EventDispatcher;
 
 /**
  * The abstract base class for Game controls and subcontrols.
+ * @private
  */
 public class AbstractControl extends EventDispatcher
 {
@@ -54,11 +55,13 @@ public class AbstractControl extends EventDispatcher
      * at once.
      *
      * Example:
+     * <code>
      * _ctrl.doBatch(function () :void {
      *     _ctrl.net.set("board", new Array());
      *     _ctrl.net.set("scores", new Array());
      *     _ctrl.net.set("captures", 0);
      * });
+     * </code>
      */
     public function doBatch (fn :Function) :void
     {
@@ -96,7 +99,7 @@ public class AbstractControl extends EventDispatcher
     {
         // Ideally we want to not be an EventDispatcher so that people
         // won't try to do this on us, but if we do that, then some other
-        // object will be the target during dispatch, and that's confusing.
+        // object will be the target during dispatch, and that's weird.
         throw new IllegalOperationError();
     }
 
@@ -109,6 +112,7 @@ public class AbstractControl extends EventDispatcher
         try {
             super.dispatchEvent(event);
         } catch (err :Error) {
+            // AFAIK, this will never happen: dispatchEvent catches and copes with all exceptions.
             trace("Error dispatching event to user game.");
             trace(err.getStackTrace());
         }

src/as/com/threerings/ezgame/AbstractGameControl.as

@@ -42,6 +42,7 @@ import flash.geom.Point;
 
 /**
  * Abstract base class for GameControl implementations.
+ * @private
  */
 public class AbstractGameControl extends AbstractControl
 {

src/as/com/threerings/ezgame/AbstractSubControl.as

@@ -25,9 +25,13 @@ import flash.errors.IllegalOperationError;
 
 /**
  * Abstract base class. Do not instantiate.
+ * @private
  */
 public class AbstractSubControl extends AbstractControl
 {
+    /**
+     * @private
+     */
     public function AbstractSubControl (parent :AbstractControl)
     {
         super();

src/as/com/threerings/ezgame/EZBagsSubControl.as

@@ -34,6 +34,9 @@ package com.threerings.ezgame {
  */
 public class EZBagsSubControl extends AbstractSubControl
 {
+    /**
+     * @private Constructed via EZGameControl.
+     */
     public function EZBagsSubControl (parent :AbstractControl)
     {
         super(parent);

src/as/com/threerings/ezgame/EZEvent.as

@@ -1,48 +0,0 @@
-//
-// $Id$
-//
-// Vilya library - tools for developing networked games
-// Copyright (C) 2002-2007 Three Rings Design, Inc., All Rights Reserved
-// http://www.threerings.net/code/vilya/
-//
-// This library is free software; you can redistribute it and/or modify it
-// under the terms of the GNU Lesser General Public License as published
-// by the Free Software Foundation; either version 2.1 of the License, or
-// (at your option) any later version.
-//
-// This library is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-// Lesser General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public
-// License along with this library; if not, write to the Free Software
-// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-package com.threerings.ezgame {
-
-import flash.events.Event;
-
-/**
- */
-public /*abstract*/ class EZEvent extends Event
-{
-    /**
-     * Access the game control to which this event applies.
-     * Note: you will need to cast this to the appropriate GameControl type.
-     */
-    public function get gameControl () :AbstractGameControl
-    {
-        return _gameCtrl;
-    }
-
-    public function EZEvent (type :String, gameCtrl :Object)
-    {
-        super(type);
-        _gameCtrl = gameCtrl as AbstractGameControl;
-    }
-
-    /** The game control for this event. @private */
-    protected var _gameCtrl :AbstractGameControl;
-}
-}

src/as/com/threerings/ezgame/EZGameControl.as

@@ -26,6 +26,9 @@ import flash.display.DisplayObject;
 /**
  * The single point of control for each client in your multiplayer EZGame.
  *
+ * <b>If you are creating a game for Whirled, you should use WhirledGameControl.</b>
+ * @see com.whirled.WhirledGameControl
+ * 
  * Usage: Usually, in your top-level movieclip/sprite:
  * _ctrl = new EZGameControl(this);
  * 

src/as/com/threerings/ezgame/EZGameSubControl.as

@@ -90,6 +90,9 @@ package com.threerings.ezgame {
  */
 public class EZGameSubControl extends AbstractSubControl
 {
+    /**
+     * @private Constructed via EZGameControl.
+     */
     public function EZGameSubControl (parent :AbstractGameControl)
     {
         super(parent);
@@ -295,7 +298,7 @@ public class EZGameSubControl extends AbstractSubControl
      */
     private function controlDidChange_v1 () :void
     {
-        dispatch(new StateChangedEvent(StateChangedEvent.CONTROL_CHANGED, _parent));
+        dispatch(new StateChangedEvent(StateChangedEvent.CONTROL_CHANGED));
     }
 
     /**
@@ -303,7 +306,7 @@ public class EZGameSubControl extends AbstractSubControl
      */
     private function turnDidChange_v1 () :void
     {
-        dispatch(new StateChangedEvent(StateChangedEvent.TURN_CHANGED, _parent));
+        dispatch(new StateChangedEvent(StateChangedEvent.TURN_CHANGED));
     }
 
     /**
@@ -311,8 +314,8 @@ public class EZGameSubControl extends AbstractSubControl
      */
     private function gameStateChanged_v1 (started :Boolean) :void
     {
-        dispatch(new StateChangedEvent(started ? StateChangedEvent.GAME_STARTED :
+        dispatch(new StateChangedEvent(started ? StateChangedEvent.GAME_STARTED
-                                       StateChangedEvent.GAME_ENDED, _parent));
+                                               : StateChangedEvent.GAME_ENDED));
     }
 
     /**
@@ -320,8 +323,8 @@ public class EZGameSubControl extends AbstractSubControl
      */
     private function roundStateChanged_v1 (started :Boolean) :void
     {
-        dispatch(new StateChangedEvent(started ? StateChangedEvent.ROUND_STARTED :
+        dispatch(new StateChangedEvent(started ? StateChangedEvent.ROUND_STARTED
-                                       StateChangedEvent.ROUND_ENDED, _parent));
+                                               : StateChangedEvent.ROUND_ENDED));
     }
 
     /**
@@ -330,8 +333,8 @@ public class EZGameSubControl extends AbstractSubControl
     private function occupantChanged_v1 (occupantId :int, player :Boolean, enter :Boolean) :void
     {
         dispatch(new OccupantChangedEvent(
-                     enter ? OccupantChangedEvent.OCCUPANT_ENTERED :
+            enter ? OccupantChangedEvent.OCCUPANT_ENTERED
-                     OccupantChangedEvent.OCCUPANT_LEFT, _parent, occupantId, player));
+                  : OccupantChangedEvent.OCCUPANT_LEFT, occupantId, player));
     }
 
     /**
@@ -339,7 +342,7 @@ public class EZGameSubControl extends AbstractSubControl
      */
     private function userChat_v1 (speaker :int, message :String) :void
     {
-        dispatch(new UserChatEvent(_parent, speaker, message));
+        dispatch(new UserChatEvent(speaker, message));
     }
 
     /** Contains any custom game configuration data. @private */

src/as/com/threerings/ezgame/EZLocalSubControl.as

@@ -52,6 +52,9 @@ import flash.geom.Point;
  */
 public class EZLocalSubControl extends AbstractSubControl
 {
+    /**
+     * @private Constructed via EZGameControl.
+     */
     public function EZLocalSubControl (parent :AbstractGameControl)
     {
         super(parent);
@@ -130,7 +133,7 @@ public class EZLocalSubControl extends AbstractSubControl
     {
         super.populateProperties(o);
 
-        o["dispatchEvent_v1"] = dispatch; // for re-dispatching key events
+        o["dispatchEvent_v1"] = dispatch; // for re-dispatching keyboard events
         o["sizeChanged_v1"] = sizeChanged_v1;
     }
 
@@ -139,7 +142,7 @@ public class EZLocalSubControl extends AbstractSubControl
      */
     private function sizeChanged_v1 (size :Point) :void
     {
-        dispatch(new SizeChangedEvent(_parent, size));
+        dispatch(new SizeChangedEvent(size));
     }
 }
 }

src/as/com/threerings/ezgame/EZNetSubControl.as

@@ -43,6 +43,9 @@ package com.threerings.ezgame {
  */
 public class EZNetSubControl extends AbstractSubControl
 {
+    /**
+     * @private Constructed via EZGameControl.
+     */
     public function EZNetSubControl (parent :AbstractGameControl)
     {
         super(parent);
@@ -164,7 +167,7 @@ public class EZNetSubControl extends AbstractSubControl
     private function propertyWasSet_v1 (
         name :String, newValue :Object, oldValue :Object, index :int) :void
     {
-        dispatch(new PropertyChangedEvent(_parent, name, newValue, oldValue, index));
+        dispatch(new PropertyChangedEvent(name, newValue, oldValue, index));
     }
 
     /**
@@ -172,7 +175,7 @@ public class EZNetSubControl extends AbstractSubControl
      */
     private function messageReceived_v1 (name :String, value :Object) :void
     {
-        dispatch(new MessageReceivedEvent(_parent, name, value));
+        dispatch(new MessageReceivedEvent(name, value));
     }
 
     /** Game properties. @private */

src/as/com/threerings/ezgame/EZPlayerSubControl.as

@@ -27,6 +27,9 @@ package com.threerings.ezgame {
  */
 public class EZPlayerSubControl extends AbstractSubControl
 {
+    /**
+     * @private Constructed via EZGameControl
+     */
     public function EZPlayerSubControl (parent :AbstractGameControl)
     {
         super(parent);

src/as/com/threerings/ezgame/EZSeatingSubControl.as

@@ -29,6 +29,9 @@ package com.threerings.ezgame {
 // TODO: methods for allowing a player to pick a seat in SEATED_CONTINUOUS games.
 public class EZSeatingSubControl extends AbstractSubControl
 {
+    /**
+     * @private Constructed via EZGameControl.
+     */
     public function EZSeatingSubControl (parent :AbstractControl, game :EZGameSubControl)
     {
         super(parent);

src/as/com/threerings/ezgame/EZServicesSubControl.as

@@ -27,6 +27,9 @@ package com.threerings.ezgame {
  */
 public class EZServicesSubControl extends AbstractSubControl
 {
+    /**
+     * @private Constructed via EZGameControl.
+     */
     public function EZServicesSubControl (parent :AbstractGameControl)
     {
         super(parent);

src/as/com/threerings/ezgame/MessageReceivedEvent.as

@@ -26,7 +26,7 @@ import flash.events.Event;
 /**
  * Dispatched on the 'net' subcontrol when a message is sent by any client.
  */
-public class MessageReceivedEvent extends EZEvent
+public class MessageReceivedEvent extends Event
 {
     /**
      * The type of all MessageReceivedEvents.
@@ -51,10 +51,9 @@ public class MessageReceivedEvent extends EZEvent
         return _value;
     }
 
-    public function MessageReceivedEvent (
+    public function MessageReceivedEvent (messageName :String, value :Object)
-        gameCtrl :Object, messageName :String, value :Object)
     {
-        super(MESSAGE_RECEIVED, gameCtrl);
+        super(MESSAGE_RECEIVED);
         _name = messageName;
         _value = value;
     }
@@ -67,10 +66,13 @@ public class MessageReceivedEvent extends EZEvent
 
     override public function clone () :Event
     {
-        return new MessageReceivedEvent(_gameCtrl, _name, _value);
+        return new MessageReceivedEvent(_name, _value);
     }
 
+    /** @private */
     protected var _name :String;
+
+    /** @private */
     protected var _value :Object;
 }
 }

src/as/com/threerings/ezgame/OccupantChangedEvent.as

@@ -23,7 +23,13 @@ package com.threerings.ezgame {
 
 import flash.events.Event;
 
-public class OccupantChangedEvent extends EZEvent
+/**
+ * Dispatched when an occupant enters or leaves.
+ *
+ * If a watcher becomes a player, you may get an OCCUPANT_LEFT event where player == false,
+ * followed immediately by an OCCUPANT_ENTERED event where player == true.
+ */
+public class OccupantChangedEvent extends Event
 {
     /**
      * @eventType OccupantEntered
@@ -47,10 +53,9 @@ public class OccupantChangedEvent extends EZEvent
         return _player;
     }
 
-    public function OccupantChangedEvent (
+    public function OccupantChangedEvent (type :String, occupantId :int, player :Boolean)
-        type :String, gameCtrl :Object, occupantId :int, player :Boolean)
     {
-        super(type, gameCtrl);
+        super(type);
         _occupantId = occupantId;
         _player = player;
     }
@@ -64,7 +69,7 @@ public class OccupantChangedEvent extends EZEvent
 
     override public function clone () :Event
     {
-        return new OccupantChangedEvent(type, _gameCtrl, _occupantId, _player);
+        return new OccupantChangedEvent(type, _occupantId, _player);
     }
 
     /** @private */

src/as/com/threerings/ezgame/PropertyChangedEvent.as

@@ -27,7 +27,7 @@ import flash.events.Event;
  * Property change events are dispatched after the property change was
  * validated on the server.
  */
-public class PropertyChangedEvent extends EZEvent
+public class PropertyChangedEvent extends Event
 {
     /**
      * The type of a property change event.
@@ -46,6 +46,8 @@ public class PropertyChangedEvent extends EZEvent
 
     /**
      * Get the property's new value.
+     * Note: if index is not -1 then this value is merely one element in an array that
+     * may be fully accessed using the 'net' subcontrol.
      */
     public function get newValue () :Object
     {
@@ -72,10 +74,9 @@ public class PropertyChangedEvent extends EZEvent
      * Constructor.
      */
     public function PropertyChangedEvent (
-        gameCtrl :Object, propName :String, newValue :Object,
+        propName :String, newValue :Object, oldValue :Object, index :int = -1)
-        oldValue :Object, index :int = -1)
     {
-        super(PROPERTY_CHANGED, gameCtrl);
+        super(PROPERTY_CHANGED);
         _name = propName;
         _newValue = newValue;
         _oldValue = oldValue;
@@ -90,7 +91,7 @@ public class PropertyChangedEvent extends EZEvent
 
     override public function clone () :Event
     {
-        return new PropertyChangedEvent(_gameCtrl, _name, _newValue, _oldValue, _index);
+        return new PropertyChangedEvent(_name, _newValue, _oldValue, _index);
     }
 
     /** @private */

src/as/com/threerings/ezgame/SizeChangedEvent.as

@@ -29,7 +29,7 @@ import flash.geom.Point;
  * Dispatched when the size of the game area changes, for example as a result of the user
  * resizing their browser window.
  */
-public class SizeChangedEvent extends EZEvent
+public class SizeChangedEvent extends Event
 {
     /**
      * The type of this event.
@@ -50,9 +50,9 @@ public class SizeChangedEvent extends EZEvent
     /**
      * Constructor.
      */
-    public function SizeChangedEvent (gameCtrl :Object, size :Point)
+    public function SizeChangedEvent (size :Point)
     {
-        super(SIZE_CHANGED, gameCtrl);
+        super(SIZE_CHANGED);
         _size = size;
     }
 
@@ -63,7 +63,7 @@ public class SizeChangedEvent extends EZEvent
 
     override public function clone () :Event
     {
-        return new SizeChangedEvent(_gameCtrl, _size.clone());
+        return new SizeChangedEvent(_size.clone()); // since _size is mutable
     }
 
     /** Our implementation details. @private */

src/as/com/threerings/ezgame/StateChangedEvent.as

@@ -26,7 +26,7 @@ import flash.events.Event;
 /**
  * Dispatched when the state of the game has changed.
  */
-public class StateChangedEvent extends EZEvent
+public class StateChangedEvent extends Event
 {
     /**
      * Indicates that the game has transitioned to a started state.
@@ -65,9 +65,9 @@ public class StateChangedEvent extends EZEvent
     // TODO: move to own event?
     public static const TURN_CHANGED :String = "TurnChanged";
 
-    public function StateChangedEvent (type :String, gameCtrl :Object)
+    public function StateChangedEvent (type :String)
     {
-        super(type, gameCtrl);
+        super(type);
     }
 
     override public function toString () :String
@@ -77,7 +77,7 @@ public class StateChangedEvent extends EZEvent
 
     override public function clone () :Event
     {
-        return new StateChangedEvent(type, _gameCtrl);
+        return new StateChangedEvent(type);
     }
 }
 }

src/as/com/threerings/ezgame/UserChatEvent.as

@@ -26,7 +26,7 @@ import flash.events.Event;
 /**
  * Dispatched when a player speaks.
  */
-public class UserChatEvent extends EZEvent
+public class UserChatEvent extends Event
 {
     /**
      * The type of a property change event.
@@ -50,12 +50,9 @@ public class UserChatEvent extends EZEvent
         return _message;
     }
 
-    /**
+    public function UserChatEvent (speaker :int, message :String)
-     * Constructor.
-     */
-    public function UserChatEvent (gameCtrl :Object, speaker :int, message :String)
     {
-        super(USER_CHAT, gameCtrl);
+        super(USER_CHAT);
         _speaker = speaker;
         _message = message;
     }
@@ -67,7 +64,7 @@ public class UserChatEvent extends EZEvent
 
     override public function clone () :Event
     {
-        return new UserChatEvent(_gameCtrl, _speaker, _message);
+        return new UserChatEvent(_speaker, _message);
     }
 
     /** @private */