Comment tweaks.

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

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

@@ -27,7 +27,7 @@ import flash.events.Event;
 import flash.events.EventDispatcher;
 
 /**
- * The abstract base class for EZ controls.
+ * The abstract base class for Game controls and subcontrols.
  */
 public class AbstractControl extends EventDispatcher
 {
@@ -39,7 +39,7 @@ public class AbstractControl extends EventDispatcher
     }
 
     /**
-     * Are we connected and running inside the EZGame environment, or has someone just
+     * Are we connected and running inside the game environment, or has someone just
      * loaded up our SWF by itself?
      */
     public function isConnected () :Boolean
@@ -55,9 +55,9 @@ public class AbstractControl extends EventDispatcher
      *
      * Example:
      * _ctrl.doBatch(function () :void {
-     *     _ctrl.set("board", new Array());
-     *     _ctrl.set("scores", new Array());
-     *     _ctrl.set("captures", 0);
+     *     _ctrl.net.set("board", new Array());
+     *     _ctrl.net.set("scores", new Array());
+     *     _ctrl.net.set("captures", 0);
      * });
      */
     public function doBatch (fn :Function) :void

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

@@ -41,19 +41,20 @@ import flash.geom.Point;
 [Event(name="unload", type="flash.events.Event")]
 
 /**
- * The single point of control for each client in your multiplayer EZGame.
+ * Abstract base class for GameControl implementations.
  */
 public class AbstractGameControl extends AbstractControl
 {
     /**
-     * Create an EZGameControl object using some display object currently on the hierarchy.
-     *
-     * @param disp the display object that is the game's UI.
      * @param autoReady if true, the game will automatically be started when initialization is
      * complete, if false, the game will not start until all clients call {@link #playerReady}.
      */
     public function AbstractGameControl (disp :DisplayObject, autoReady :Boolean)
     {
+        if (disp == null || Object(this).constructor == AbstractGameControl) {
+            throw new IllegalOperationError("Abstract");
+        }
+
         createSubControls();
 
         var event :DynEvent = new DynEvent();

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

@@ -22,7 +22,15 @@
 package com.threerings.ezgame {
 
 /**
- * Contains 'bags' game services.
+ * Contains 'bags' game services. Do not instantiate this class yourself, access it
+ * via GameControl.services.bags.
+ *
+ * Bags are secret collections containing non-unique elements that are stored on the server.
+ * They can be used to implement game features where clients can't be trusted to not
+ * sniff their network.
+ * 
+ * For example you could create a bag called "dice" and fill it with [ 1, 2, 3, 4, 5, 6 ].
+ * Now you can roll the die with _ctrl.services.bags.pick("dice", 1, "diceProperty");
  */
 public class EZBagsSubControl extends AbstractSubControl
 {
@@ -41,7 +49,7 @@ public class EZBagsSubControl extends AbstractSubControl
     }
 
     /**
-     * Add to an existing bag. If it doesn't exist, it will
+     * Add values to an existing bag. If it doesn't exist, it will
      * be created.
      */
     public function addTo (bagName :String, values :Array) :void
@@ -50,7 +58,7 @@ public class EZBagsSubControl extends AbstractSubControl
     }
 
     /**
-     * Merge the specified bag into the other bag.
+     * Merge all values from the specified bag into the other bag.
      * The source bag will be destroyed. The elements from
      * the source bag will be shuffled and appended to the end
      * of the destination bag.

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

@@ -23,9 +23,6 @@ package com.threerings.ezgame {
 
 import flash.events.Event;
 
-// TODO: there may not be much point in using the standard flash event
-// architecture. I'm about thiiiiiiis close to not.
-//
 public /*abstract*/ class EZEvent extends Event
 {
     /**

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

@@ -26,7 +26,9 @@ import flash.display.DisplayObject;
 /**
  * The single point of control for each client in your multiplayer EZGame.
  *
- * TODO: lots of documentation.
+ * Usage: Usually, in your top-level movieclip/sprite:
+ * _ctrl = new EZGameControl(this);
+ * 
  */
 public class EZGameControl extends AbstractGameControl
 {

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

@@ -85,7 +85,8 @@ package com.threerings.ezgame {
 [Event(name="UserChat", type="com.threerings.ezgame.UserChatEvent")]
 
 /**
- * Access game-specific controls.
+ * Access game-specific controls. Do not instantiate this class yourself.
+ * Access it via GameControl.game.
  */
 public class EZGameSubControl extends AbstractSubControl
 {
@@ -107,6 +108,8 @@ public class EZGameSubControl extends AbstractSubControl
 
     /**
      * Get any game-specific configurations that were set up in the lobby.
+     *
+     * @return an Object containing config names mapping to their values.
      */
     public function getConfig () :Object
     {
@@ -133,7 +136,7 @@ public class EZGameSubControl extends AbstractSubControl
     }
 
     /**
-     * Returns the player ids of all occupants in the game room.
+     * Returns the player ids of all occupants in the game room: players and watchers.
      */
     public function getOccupantIds () :Array /* of playerId */
     {
@@ -143,7 +146,7 @@ public class EZGameSubControl extends AbstractSubControl
     /**
      * Get the display name of the specified occupant.  Two players may have the same name: always
      * use playerId to purposes of identification and comparison. The name is for display
-     * only. Will be null is the specified playerId is not in the game.
+     * only. Will be null is the specified playerId is not present.
      */
     public function getOccupantName (playerId :int) :String
     {

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

@@ -48,7 +48,8 @@ import flash.events.KeyboardEvent;
 import flash.geom.Point;
 
 /**
- * Access local properties of the game.
+ * Access local properties of the game. Do not instantiate this class yourself,
+ * access it via GameControl.local.
  */
 public class EZLocalSubControl extends AbstractSubControl
 {
@@ -100,7 +101,7 @@ public class EZLocalSubControl extends AbstractSubControl
     }
 
     /**
-     * Display a feedback system chat message for the local player only, no other players
+     * Display a feedback chat message for the local player only, no other players
      * or observers will see it.
      */
     public function feedback (msg :String) :void

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

@@ -36,7 +36,10 @@ package com.threerings.ezgame {
 [Event(name="msgReceived", type="com.threerings.ezgame.MessageReceivedEvent")]
 
 /**
- * Provides access to 'net' game services.
+ * Provides access to 'net' game services. Do not instantiate this class yourself,
+ * access it via GameControl.net.
+ *
+ * The 'net' subcontrol is used to communicate shared state between game clients.
  */
 public class EZNetSubControl extends AbstractSubControl
 {
@@ -46,7 +49,7 @@ public class EZNetSubControl extends AbstractSubControl
     }
 
     /**
-     * Get a property from data.
+     * Get a property value.
      */
     public function get (propName :String, index :int = -1) :Object
     {
@@ -88,15 +91,16 @@ public class EZNetSubControl extends AbstractSubControl
     /**
      * Set a property that will be distributed, but only if it's equal to the specified test value.
      *
-     * <p> Please note that, unlike in the standard set() function, the property will not be
+     * <p> Please note that, unlike in the setImmediate() function, the property will not be
      * updated right away, but will require a request to the server and a response back. For this
      * reason, there may be a considerable delay between calling testAndSet, and seeing the result
      * of the update.
      *
      * <p> The operation is 'atomic', in the sense that testing and setting take place during the
      * same server event. In comparison, a separate 'get' followed by a 'set' operation would
-     * involve two events with two network round-trips, and no guarantee that the value won't
-     * change between the events.
+     * first read the current value as seen on your client and then send a request to overwrite
+     * any value with a new value. By the time the 'set' reaches the server the old value
+     * may no longer be valid. Since that's sketchy, we have this method.
      */
     public function testAndSet (
         propName :String, newValue :Object, testValue :Object, index :int = -1) :void

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

@@ -22,7 +22,8 @@
 package com.threerings.ezgame {
 
 /**
- * Provides access to 'player' game services.
+ * Provides access to 'player' game services. Do not instantiate this class directly,
+ * instead access it via GameControl.player.
  */
 public class EZPlayerSubControl extends AbstractSubControl
 {

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

@@ -23,7 +23,8 @@ package com.threerings.ezgame {
 
 
 /**
- * Access seating information for a seated game.
+ * Access seating information for a seated game. Do not instantiate this class directly,
+ * access it via GameControl.game.seating.
  */
 // TODO: methods for allowing a player to pick a seat in SEATED_CONTINUOUS games.
 public class EZSeatingSubControl extends AbstractSubControl
@@ -61,7 +62,7 @@ public class EZSeatingSubControl extends AbstractSubControl
     }
 
     /**
-     * Get the names of the seated players, omitting any watchers.
+     * Get the names of the seated players, in the order of their seated position.
      */
     public function getPlayerNames () :Array /* of String */
     {

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

@@ -22,7 +22,8 @@
 package com.threerings.ezgame {
 
 /**
- * Provides access to 'services' game services.
+ * Provides access to 'services' game services. Do not instantiate this class yourself,
+ * access it via GameControl.services.
  */
 public class EZServicesSubControl extends AbstractSubControl
 {
@@ -79,9 +80,10 @@ public class EZServicesSubControl extends AbstractSubControl
     }
 
     /**
-     * Start the ticker with the specified name. The ticker will deliver messages to all connected 
-     * clients at the specified delay. The value of each message is a single integer, 
-     * starting with 0 and increasing by 1 with each messsage.
+     * Start the ticker with the specified name. The ticker will deliver messages
+     * (resulting in a MessageReceivedEvent being dispatched on the 'net' control)
+     * to all connected clients, at the specified delay. The value of each message is
+     * a single integer, starting with 0 and increasing by 1 with each messsage.
      */
     public function startTicker (tickerName :String, msOfDelay :int) :void
     {

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

@@ -23,6 +23,9 @@ package com.threerings.ezgame {
 
 import flash.events.Event;
 
+/**
+ * Dispatched on the 'net' subcontrol when a message is sent by any client.
+ */
 public class MessageReceivedEvent extends EZEvent
 {
     /** The type of all MessageReceivedEvents. */