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

@@ -16,11 +16,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.
@@ -51,6 +52,9 @@ class GameStartEvent(GameEvent):
     def __init__(self, frame, pid, data):
         super(GameStartEvent, self).__init__(frame, pid)
 
+        #: ???
+        self.data = data
+
 
 class PlayerLeaveEvent(GameEvent):
     """
@@ -59,6 +63,9 @@ class PlayerLeaveEvent(GameEvent):
     def __init__(self, frame, pid, data):
         super(PlayerLeaveEvent, self).__init__(frame, pid)
 
+        #: ???
+        self.data = data
+
 
 class UserOptionsEvent(GameEvent):
     """
@@ -80,7 +87,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']
@@ -127,11 +134,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,
@@ -446,13 +473,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

@@ -12,8 +12,13 @@ class MessageEvent(Event):
         Parent class for all message events.
     """
     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
 
         #: Short cut string for event class name
@@ -34,10 +39,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,9 +10,14 @@
 
 
 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
+
+        #: The second of the game (game time not real time) this event was applied
         self.second = frames >> 4
 
         #: Short cut string for event class name
@@ -30,17 +35,15 @@ def __str__(self):
 
 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.
     """
     def __init__(self, frames, data, build):
         super(PlayerStatsEvent, self).__init__(frames)
@@ -213,15 +216,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.
     """
     def __init__(self, frames, data, build):
         super(UnitBornEvent, self).__init__(frames)
@@ -253,10 +255,12 @@ def __init__(self, frames, data, build):
         #: The player object that controls this unit. 0 means neutral unit
         self.unit_controller = None
 
-        #: The x coordinate of the location
+        #: The x coordinate of the location with 4 point resolution. E.g. 13.75 recorded as 12.
+        #: Location prior to rounding marks the center of the unit footprint.
         self.x = data[5] * 4
 
-        #: The y coordinate of the location
+        #: The y coordinate of the location with 4 point resolution. E.g. 13.75 recorded as 12.
+        #: Location prior to rounding marks the center of the unit footprint.
         self.y = data[6] * 4
 
         #: The map location of the unit birth
@@ -292,10 +296,12 @@ def __init__(self, frames, data, build):
         #: The player object of the that killed the unit. Not always available.
         self.killer = None
 
-        #: The x coordinate of the location
+        #: The x coordinate of the location with 4 point resolution. E.g. 13.75 recorded as 12.
+        #: Location prior to rounding marks the center of the unit footprint.
         self.x = data[3] * 4
 
-        #: The y coordinate of the location
+        #: The y coordinate of the location with 4 point resolution. E.g. 13.75 recorded as 12.
+        #: Location prior to rounding marks the center of the unit footprint.
         self.y = data[4] * 4
 
         #: The map location the unit was killed at.
@@ -394,10 +400,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.
     """
     def __init__(self, frames, data, build):
         super(UnitInitEvent, self).__init__(frames)
@@ -429,10 +434,12 @@ def __init__(self, frames, data, build):
         #: The player object that controls this unit. 0 means neutral unit
         self.unit_controller = None
 
-        #: The x coordinate of the location
+        #: The x coordinate of the location with 4 point resolution. E.g. 13.75 recorded as 12.
+        #: Location prior to rounding marks the center of the unit footprint.
         self.x = data[5] * 4
 
-        #: The y coordinate of the location
+        #: The y coordinate of the location with 4 point resolution. E.g. 13.75 recorded as 12.
+        #: Location prior to rounding marks the center of the unit footprint.
         self.y = data[6] * 4
 
         #: The map location the unit was started at
@@ -444,9 +451,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.
     """
     def __init__(self, frames, data, build):
         super(UnitDoneEvent, self).__init__(frames)
@@ -485,7 +491,9 @@ def __init__(self, frames, data, build):
         #: A dict mapping of units that had their position updated to their positions
         self.units = dict()
 
-        #: A list of (unit_index, (x,y)) derived from the first_unit_index and items
+        #: A list of (unit_index, (x,y)) derived from the first_unit_index and items. Like the other
+        #: tracker events, these coordinates have 4 point resolution. (15,25) recorded as (12,24).
+        #: Location prior to rounding marks the center of the unit footprint.
         self.positions = list()
 
         unit_index = self.first_unit_index