From aeed76cadd2b83c0f5db1afe3c8f2045727f37bf Mon Sep 17 00:00:00 2001
From: Peter Ward <peteraward@gmail.com>
Date: Fri, 19 Sep 2014 22:22:43 +1000
Subject: docs

---
 robots/state.py | 52 +++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 49 insertions(+), 3 deletions(-)

diff --git a/robots/state.py b/robots/state.py
index 10a899e..37d2554 100644
--- a/robots/state.py
+++ b/robots/state.py
@@ -10,12 +10,26 @@ class GameState:
     """
 
     def __init__(self, board):
-        # _[y][x] = City
         self.cities = board
-        # _[x, y] = str (player id)
+        """
+        A 2D list of the city types (robots.contants.City).
+
+        Index using row-major format (state.cities[y][x]).
+        """
+
         self.allegiances = {}
-        # _[player_id] = [(x, y, energy), ...]
+        """
+        Dictionary mapping (x, y) positions to players.
+
+        Cities without allegience are not present in the dictionary.
+        """
+
         self.robots_by_player = {}
+        """
+        Dictionary mapping each player to a list of their robots.
+
+        Each robot is represented by (x, y, energy).
+        """
 
     def __hash__(self):
         return id(self)
@@ -51,10 +65,16 @@ class GameState:
 
     @property
     def players(self):
+        """List of players."""
         return self.robots_by_player.keys()
 
     @property
     def robots(self):
+        """
+        Grid of the game board, showing the 0 or 1 robot in each city.
+
+        Dictionary mapping (x, y) to either [] or [(player, energy)].
+        """
         result = defaultdict(list)
         for player, robots in self.robots_by_player.items():
             for x, y, energy in robots:
@@ -63,6 +83,9 @@ class GameState:
 
     @property
     def allegiances_by_player(self):
+        """
+        Dictionary mapping each player to a list of cities they control.
+        """
         result = defaultdict(list)
         for (x, y), player in self.allegiances.items():
             result[player].append((x, y))
@@ -70,6 +93,18 @@ class GameState:
 
     @property
     def board(self):
+        """
+        A 2D list with all available information about each city.
+
+        Each city is represented with a dictionary:
+
+        >>> {
+        ...     'city': robots.constants.City,
+        ...     'allegiance': player or None,
+        ...     'robots': [robot] or [],
+        ... }
+
+        """
         # TODO: remove this once I've figured out caching.
         self_robots = self.robots
 
@@ -90,14 +125,19 @@ class GameState:
 
     @property
     def width(self):
+        """Width of the map."""
         return len(self.cities[0])
 
     @property
     def height(self):
+        """Height of the map."""
         return len(self.cities)
 
     @property
     def factories(self):
+        """
+        Set of the (x, y) positions of all factories on the map.
+        """
         return {
             (x, y)
             for y, row in enumerate(self.cities)
@@ -107,6 +147,12 @@ class GameState:
 
     @property
     def factories_by_player(self):
+        """
+        Dictionary mapping each player to a list of factory (x, y) positions
+        they control.
+
+        The None key represents unowned factories.
+        """
         result = defaultdict(list)
         for p in self.factories:
             player = self.allegiances.get(p)
-- 
cgit v1.2.3