Add documentation

1 files changed, 59 insertions, 1 deletions

diff --git a/state.py b/state.py
index f80b557..f78fa0a 100644
--- a/state.py
+++ b/state.py
@@ -1,10 +1,30 @@
-# 
+__docformat__ = 'restructuredtext'
+
 class Category:
+    """
+    A Category is a "set" of states. The category specifies a name, certain
+    arguments that must be provided, and constraints for the values of those
+    arguments. Any possible state which meets these restrictions is in the
+    category.
+    """
+
     def __init__(self, name, **args):
+        """
+        Categories are constructed with a `name` and a series of keyword
+        arguments. `name` is a string. Each keyword argument that is specified
+        is the name of a state argument a state must posess to be considered to
+        be a member of the category. If the value of the keyword argument is
+        `None` then the state argument can have any value, otherwise the value is a string
+        and specifies a mandatory value for the state argument.
+        """
         self.args = args
         self.name = name
 
     def equiv(self, other):
+        """
+        Returns True if any state in the Category `other` is in this Category. Note that
+        this is *intransitive*; ``a.equiv(b)`` is not the same as ``b.equiv(a)``.
+        """
         if self.name != other.name: return False
         for key, value in self.args.iteritems():
             if not other.args.has_key(key): return False
@@ -14,6 +34,10 @@ class Category:
         return True
     
     def intersect(self, other):
+        """
+        Returns a new category consisting only of states that are in this
+        category, and the category `other`.
+        """
         if self.name != other.name: return None
         args = {}
         for key in list(set(self.args.keys() + other.args.keys())):
@@ -54,6 +78,9 @@ class Category:
         return self.name == other.name and self.argstup() == other.argstup()
 
     def argstup(self):
+        """
+        Returns arguments as a sorted tuple.
+        """
         retval = []
         keys = self.args.keys()
         keys.sort()
@@ -62,6 +89,10 @@ class Category:
         return tuple(retval)
 
     def fill(self, info):
+        """
+        Set any arguments matched by this category that don't have explicitly
+        required values to require the values in `info`.
+        """
         args = {}
         for key, value in self.args.iteritems():
             if value != None or not info.has_key(key):
@@ -71,11 +102,22 @@ class Category:
         return Category(self.name, **args)
 
 class StateMachine:
+    """
+    The state machine contains a list of dependencies between states, and a list
+    of states which are "up."
+    """
+
     def __init__(self):
+        """
+        Create a new state machine
+        """
         self.holds = {}
         self.deps = []
 
     def assert_state(self, cat):
+        """
+        Move states in the given Category `cat` from down to up.
+        """
         found = None
         for dependency in self.get_applicable_deps(cat):
             res = self.get_satisfied_states(cat, dependency)
@@ -95,6 +137,11 @@ class StateMachine:
         return True
 
     def intersect_list(self, cats1, cats2):
+        """
+        Given two lists of categories, return a list of categories such that a
+        state appearing in at least one category in each list will appear in at
+        least one category in the returned list.
+        """
         retval = set()
         found = set()
         for x in cats1:
@@ -110,12 +157,20 @@ class StateMachine:
         return (retval | ((cats1 & cats2) - found))
 
     def add_hold(self, cat):
+        """
+        Add a hold to a state. Does not check dependencies.
+        """
         if self.holds.has_key(cat):
             self.holds[cat] = self.holds[cat] + 1
         else:
             self.holds[cat] = 1
 
     def get_satisfied_states(self, dependents, dependencies):
+        """
+        Given that states in `dependents` depend on states in `dependencies`,
+        return a new Category that contains only the states in `dependents` that
+        could match states in `dependencies`.
+        """
         retval = []
         for key, val in self.holds.iteritems():
             if dependencies.equiv(key) and val > 0:
@@ -123,6 +178,9 @@ class StateMachine:
         return set(retval)
 
     def get_applicable_deps(self, cat):
+        """
+        Find dependencies that might apply to members of `cat`
+        """
         retval = []
         for (x, y) in self.deps:
             if x.equiv(cat):