Misc. documentation improvements.

Author: GraylinKim

docs/source/events/game.rst

@@ -11,4 +11,3 @@ computer player.
 
 .. automodule:: sc2reader.events.game
 	:members:
-	:undoc-members:

docs/source/events/message.rst

@@ -3,8 +3,5 @@
 Message Events
 ===================
 
-Coming soon!
-
 .. automodule:: sc2reader.events.message
 	:members:
-	:undoc-members:

docs/source/events/tracker.rst

@@ -9,4 +9,3 @@ are also periodically recorded to snapshot aspects of the current game state.
 
 .. automodule:: sc2reader.events.tracker
 	:members:
-	:undoc-members:

sc2reader/events/game.py

@@ -18,11 +18,12 @@ class GameEvent(Event):
     def __init__(self, frame, pid):
         #: The id of the player generating the event. This is 16 for global non-player events.
         #: Prior to Heart of the Swarm this was the player id. Since HotS it is
-        #: now the user id (uid), we still call it pid for backwards compatibility.
+        #: now the user id (uid), we still call it pid for backwards compatibility. You shouldn't
+        #: ever need to use this; use :attr:`player` instead.
         self.pid = pid
 
         #: A reference to the :class:`~sc2reader.objects.Player` object representing
-        #: this player in the replay. Not available for global events (:attr:`pid` = 16)
+        #: this player in the replay. Not available for global events (:attr:`is_local` = False)
         self.player = None
 
         #: The frame of the game that this event was recorded at. 16 frames per game second.
@@ -53,6 +54,9 @@ class GameStartEvent(GameEvent):
     def __init__(self, frame, pid, data):
         super(GameStartEvent, self).__init__(frame, pid)
 
+        #: ???
+        self.data = data
+
 
 class PlayerLeaveEvent(GameEvent):
     """
@@ -64,6 +68,9 @@ class PlayerLeaveEvent(GameEvent):
     def __init__(self, frame, pid, data):
         super(PlayerLeaveEvent, self).__init__(frame, pid)
 
+        #: ???
+        self.data = data
+
 
 class UserOptionsEvent(GameEvent):
     """
@@ -88,7 +95,7 @@ def __init__(self, frame, pid, data):
         self.sync_checksumming_enabled = data['sync_checksumming_enabled']
 
         #:
-        is_map_to_map_transition = data['is_map_to_map_transition']
+        self.is_map_to_map_transition = data['is_map_to_map_transition']
 
         #:
         self.use_ai_beacons = data['use_ai_beacons']
@@ -144,11 +151,31 @@ def __init__(self, frame, pid, data):
         #: Flags on the command???
         self.flags = data['flags']
 
-        #: A dictionary of possible ability flags. Flag names are: alternate,
-        #: queued, preempt, smart_click, smart_rally, subgroup, set_autocast,
-        #: set_autocast_on, user, data_a, data_b, data_passenger, data_abil_queue_order_id,
-        #: ai, ai_ignore_on_finish, is_order, script, homogenous_interruption,
-        #: minimap, repeat, dispatch_to_other_unit, and target_self
+        #: A dictionary of possible ability flags. Flags are:
+        #:
+        #: * alternate
+        #: * queued
+        #: * preempt
+        #: * smart_click
+        #: * smart_rally
+        #: * subgroup
+        #: * set_autocast,
+        #: * set_autocast_on
+        #: * user
+        #: * data_a
+        #: * data_b
+        #: * data_passenger
+        #: * data_abil_queue_order_id,
+        #: * ai
+        #: * ai_ignore_on_finish
+        #: * is_order
+        #: * script
+        #: * homogenous_interruption,
+        #: * minimap
+        #: * repeat
+        #: * dispatch_to_other_unit
+        #: * target_self
+        #:
         self.flag = dict(
             alternate=0x1 & self.flags != 0,
             queued=0x2 & self.flags != 0,
@@ -491,13 +518,13 @@ class CameraEvent(GameEvent):
     def __init__(self, frame, pid, data):
         super(CameraEvent, self).__init__(frame, pid)
 
-        #: The x coordinate of the center? of the camera
+        #: The x coordinate of the center of the camera
         self.x = (data['target']['x'] if data['target'] is not None else 0)/256.0
 
-        #: The y coordinate of the center? of the camera
+        #: The y coordinate of the center of the camera
         self.y = (data['target']['y'] if data['target'] is not None else 0)/256.0
 
-        #: The location of the center? of the camera
+        #: The location of the center of the camera
         self.location = (self.x, self.y)
 
         #: The distance to the camera target ??

sc2reader/events/message.py

@@ -11,8 +11,13 @@ class MessageEvent(Event):
     name = 'MessageEvent'
 
     def __init__(self, frame, pid):
+        #: The user id (or player id for older replays) of the person that generated the event.
         self.pid = pid
+
+        #: The frame of the game this event was applied
         self.frame = frame
+
+        #: The second of the game (game time not real time) this event was applied
         self.second = frame >> 4
 
     def _str_prefix(self):
@@ -29,10 +34,19 @@ class ChatEvent(MessageEvent):
 
     def __init__(self, frame, pid, target, text):
         super(ChatEvent, self).__init__(frame, pid)
+        #: The numerical target type. 0 = to all; 2 = to allies; 4 = to observers.
         self.target = target
+
+        #: The text of the message.
         self.text = text
+
+        #: Flag marked true of message was to all.
         self.to_all = (self.target == 0)
+
+        #: Flag marked true of message was to allies.
         self.to_allies = (self.target == 2)
+
+        #: Flag marked true of message was to observers.
         self.to_observers = (self.target == 4)
 
 

sc2reader/events/tracker.py

@@ -10,10 +10,15 @@
 
 
 class TrackerEvent(Event):
+    """
+    Parent class for all tracker events.
+    """
     def __init__(self, frames):
         #: The frame of the game this event was applied
         self.frame = frames
-        self.second = frames >>4
+
+        #: The second of the game (game time not real time) this event was applied
+        self.second = frames >> 4
 
     def load_context(self, replay):
         pass
@@ -45,17 +50,15 @@ def __init__(self, frames, data, build):
 
 class PlayerStatsEvent(TrackerEvent):
     """
-        Player Stats events are generated for all players that were in the game
-        even if they've since left every 10 seconds. An additional set of stats
-        events are generated at the end of the game.
+    Player Stats events are generated for all players that were in the game even if they've since
+    left every 10 seconds. An additional set of stats events are generated at the end of the game.
 
-        When a player leaves the game, a single PlayerStatsEvent is generated
-        for that player and no one else. That player continues to generate
-        PlayerStatsEvents at 10 second intervals until the end of the game.
+    When a player leaves the game, a single PlayerStatsEvent is generated for that player and no
+    one else. That player continues to generate PlayerStatsEvents at 10 second intervals until the
+    end of the game.
 
-        In 1v1 games, the above behavior can cause the losing player to have 2
-        events generated at the end of the game. One for leaving and one for
-        the  end of the game.
+    In 1v1 games, the above behavior can cause the losing player to have 2 events generated at the
+    end of the game. One for leaving and one for the  end of the game.
     """
 
     name = 'PlayerStatsEvent'
@@ -231,15 +234,14 @@ def __str__(self):
 
 class UnitBornEvent(TrackerEvent):
     """
-    Generated when a unit is created in a finished state in the game. Examples
-    include the Marine, Zergling, and Zealot (when trained from a gateway).
-    Units that enter the game unfinished (all buildings, warped in units) generate
-    a :class:`UnitInitEvent` instead.
-
-    Unfortunately, units that are born do not have events marking their beginnings
-    like :class:`UnitInitEvent` and :class:`UnitDoneEvent` do. The closest thing to
-    it are the :class:`~sc2reader.event.game.AbilityEvent` game events where the ability
-    is a train unit command.
+    Generated when a unit is created in a finished state in the game. Examples include the Marine,
+    Zergling, and Zealot (when trained from a gateway). Units that enter the game unfinished (all
+    buildings, warped in units) generate a :class:`UnitInitEvent` instead.
+
+    Unfortunately, units that are born do not have events marking their beginnings like
+    :class:`UnitInitEvent` and :class:`UnitDoneEvent` do. The closest thing to it are the
+    :class:`~sc2reader.event.game.AbilityEvent` game events where the ability is a train unit
+    command.
     """
 
     name = 'UnitBornEvent'
@@ -441,10 +443,9 @@ def __str__(self):
 
 class UnitInitEvent(TrackerEvent):
     """
-    The counter part to :class:`UnitDoneEvent`, generated by the game engine
-    when a unit is initiated. This applies only to units which are started
-    in game before they are finished. Primary examples being buildings and
-    warp-in units.
+    The counter part to :class:`UnitDoneEvent`, generated by the game engine when a unit is
+    initiated. This applies only to units which are started in game before they are finished.
+    Primary examples being buildings and warp-in units.
     """
 
     name = 'UnitInitEvent'
@@ -501,9 +502,8 @@ def __str__(self):
 
 class UnitDoneEvent(TrackerEvent):
     """
-    The counter part to the :class:`UnitInitEvent`, generated by the game engine
-    when an initiated unit is completed. E.g. warp-in finished, building finished,
-    morph complete.
+    The counter part to the :class:`UnitInitEvent`, generated by the game engine when an initiated
+    unit is completed. E.g. warp-in finished, building finished, morph complete.
     """
 
     name = 'UnitDoneEvent'