Updates to the project documentation.

Author: GraylinKim

sc2reader/data/__init__.py

@@ -38,19 +38,26 @@ class Unit(object):
     """
 
     def __init__(self, unit_id, flags):
-        #: A reference to the player that owns this unit
+        #: A reference to the player that currently owns this unit. Only available for 2.0.8+ replays.
         self.owner = None
 
-        #: The frame the unit was started at
+        #: The frame the unit was started at. Only available for 2.0.8+ replays.
+        #: Specifically, it is the frame the :class:`~sc2reader.events.tracker.UnitInitEvent` is received. For units
+        #: that are born and not initiated this will be the same as :attr:`finished_at`.
         self.started_at = None
 
-        #: The frame the unit was finished at
+        #: The frame the unit was finished at. Only available for 2.0.8+ replays.
+        #: Specifically, it is the frame that the :class:`~sc2reader.events.tracker.UnitDoneEvent` is received. For units
+        #: that are born and not initiated this will be the same as :attr:`started_at`.
         self.finished_at = None
 
-        #: The frame the unit died at
+        #: The frame the unit died at. Only available for 2.0.8+ replays.
+        #: Specifically, it is the frame that the :class:`~sc2reader.events.tracker.UnitDiedEvent` is received.
         self.died_at = None
 
-        #: A reference to the player that killed this unit. Not always available.
+        #: A reference to the player that killed this unit. Only available for 2.0.8+ replays.
+        #: This value is not set if the killer is unknown or not relevant (morphed into a
+        #: different unit or used to create a building, etc)
         self.killed_by = None
 
         #: The unique in-game id for this unit. The id can sometimes be zero because

sc2reader/events/tracker.py

@@ -39,6 +39,7 @@ class PlayerStatsEvent(TrackerEvent):
         events generated at the end of the game. One for leaving and one for
         the  end of the game.
     """
+
     name = 'PlayerStatsEvent'
 
     def __init__(self, frames, data, build):
@@ -211,6 +212,13 @@ 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.
+    """
+
     name = 'UnitBornEvent'
 
     def __init__(self, frames, data, build):
@@ -257,6 +265,11 @@ def __str__(self):
 
 
 class UnitDiedEvent(TrackerEvent):
+    """
+    Generated when a unit dies or is removed from the game for any reason. Reasons include
+    morphing, merging, and getting killed.
+    """
+
     name = 'UnitDiedEvent'
 
     def __init__(self, frames, data, build):
@@ -375,6 +388,13 @@ 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.
+    """
+
     name = 'UnitInitEvent'
 
     def __init__(self, frames, data, build):
@@ -417,10 +437,16 @@ def __init__(self, frames, data, build):
         self.location = (self.x, self.y)
 
     def __str__(self):
-        return self._str_prefix()+"{0: >15} - Unit inititated {1}".format(self.unit_upkeeper, self.unit)
+        return self._str_prefix()+"{0: >15} - Unit initiated {1}".format(self.unit_upkeeper, self.unit)
 
 
 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.
+    """
+
     name = 'UnitDoneEvent'
 
     def __init__(self, frames, data, build):