# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1266161292 -3600
# Node ID 4125a2a53e5e69b83bd1cc7b0c5f99bb916583b2
# Parent  0b86019411616eb4f8035d2aa8b241070b34015a
Added comments for the attribute usage namespace attributes.
Updated the docstring, including comments from the module body.

diff -r 0b8601941161 -r 4125a2a53e5e micropython/data.py
--- a/micropython/data.py	Fri Feb 12 01:34:28 2010 +0100
+++ b/micropython/data.py	Sun Feb 14 16:28:12 2010 +0100
@@ -1,7 +1,11 @@
 #!/usr/bin/env python
 
 """
-Data classes.
+Program data structures. There are two separate kinds of structures: those with
+context, which are the values manipulated by programs, and those without
+context, which are typically constant things which are stored alongside the
+program but which are wrapped in context-dependent structures in the running
+program.
 
 Copyright (C) 2007, 2008, 2009, 2010 Paul Boddie <paul@boddie.org.uk>
 
@@ -20,6 +24,10 @@
 
 --------
 
+The principal value structure class in this module is the Attr class which
+represents attributes of objects and retains the context of each reference to an
+attribute. This class models program behaviour at run-time.
+
 The central data structure classes in this module are the following:
 
   * Class
@@ -123,12 +131,24 @@
         # Specific namespaces should define known names during initialisation.
         # For example, functions can define names belonging to parameters.
 
+        # Attribute usage, defining a consensus for each name.
+
         self.attributes_used = [{}] # stack of usage
         self.attribute_shelves = [] # stack of unmerged definitions
+
+        # Attribute usage abandonment, where the usage will not contribute to
+        # the consensus.
+
         self.abandon_attributes = 0 # used when a block will never contribute
         self.abandoned_shelves = []
+
+        # Attribute users, defining names which use attributes.
+
         self.attribute_users = [{}] # stack of assignments
         self.user_shelves = []
+
+        # Define attribute usage to identify active program sections.
+
         self.all_attributes_used = []
 
     # Attribute/name definition and access.
@@ -369,17 +389,30 @@
         self.all_attributes_used.append(defs[name])
 
     def _new_branchpoint(self):
+
+        """
+        Establish a new branchpoint where several control-flow branches diverge
+        and subsequently converge.
+        """
+
         self.attribute_shelves.append([])
         self.abandoned_shelves.append([])
         self.user_shelves.append([])
 
     def _new_branch(self):
+
+        """
+        Establish a new control-flow branch, transferring attribute usage to
+        the new branch so that it may be augmented for each name locally.
+        """
+
         d = {}
         for name, attrnames in self.attributes_used[-1].items():
             d[name] = set(attrnames)
         self.attributes_used.append(d)
 
-        # The users apply also to the new branch.
+        # In the new branch, usage does not necessarily feed back to the users
+        # immediately.
 
         self.attribute_users.append({})
 
@@ -478,11 +511,7 @@
                 if not active.has_key(name) or attrnames.issuperset(active[name]):
                     self.all_attributes_used.append(attrnames)
 
-# Program data structures. There are two separate kinds of structures: those
-# with context, which are the values manipulated by programs, and those without
-# context, which are typically constant things which are stored alongside the
-# program but which are wrapped in context-dependent structures in the running
-# program.
+# Program data structures.
 
 class Attr: