# HG changeset patch
# User paulb@localhost.localdomain
# Date 1182708367 -7200
# Node ID 4d9f6d455b5b23a6af1e67c50e6f76927d62a598
# Parent  60a816e55966dc33d19675357a8dfd47cbde7e9e
Updated docstrings, made minor stylistic changes.


diff -r 60a816e55966 -r 4d9f6d455b5b simplify/__init__.py
--- a/simplify/__init__.py	Sun Jun 24 20:05:24 2007 +0200
+++ b/simplify/__init__.py	Sun Jun 24 20:06:07 2007 +0200
@@ -22,8 +22,8 @@
 
 --------
 
-To use this module, an importer should be constructed and the load method used.
-Here, the standard path for module searching is used:
+To use this module, an importer should be constructed and the load_from_file
+method used. Here, the standard path for module searching is employed:
 
 importer = Importer(sys.path)
 importer.load_from_file(builtins)
@@ -56,6 +56,9 @@
         self.modules = {}
 
     def get_modules(self):
+
+        "Return all modules known to the importer."
+
         return self.modules.values()
 
     def find_in_path(self, name):
@@ -143,27 +146,40 @@
         if self.modules.has_key(name):
             return Attribute(None, self.modules[name])
 
+        # Split the name into path components, and try to find the uppermost in
+        # the search path.
+
         path = name.split(".")
         m = self.find_in_path(path[0])
         if not m:
             return None # NOTE: Import error.
         d, filename = m
 
+        # Either acquire a reference to an already-imported module, or load the
+        # module from a file.
+
         if self.modules.has_key(path[0]):
             top = module = self.modules[path[0]]
         else:
             top = module = self.load_from_file(filename, builtins, path[0])
 
+        # For hierarchical names, traverse each path component...
+
         if len(path) > 1:
             path_so_far = path[:1]
             for p in path[1:]:
                 path_so_far.append(p)
+
+                # Find the package or module concerned.
+
                 m = self.find(d, p)
                 if not m:
                     return None # NOTE: Import error.
                 d, filename = m
                 module_name = ".".join(path_so_far)
 
+                # Either reference an imported module or load one from a file.
+
                 if self.modules.has_key(module_name):
                     submodule = self.modules[module_name]
                 else:
@@ -174,6 +190,8 @@
                 module.namespace[p] = [Attribute(None, submodule)]
                 module = submodule
 
+        # Return either the deepest or the uppermost module.
+
         if alias:
             return Attribute(None, module)
         else:
@@ -192,6 +210,8 @@
             else:
                 module_name = "__main__"
 
+        # Simplify, fix names, and annotate the module.
+
         module = simplify.ast.simplify(name, builtins is None, module_name)
         simplify.fixnames.fix(module, builtins)
         if self.annotate:
diff -r 60a816e55966 -r 4d9f6d455b5b simplify/ast.py
--- a/simplify/ast.py	Sun Jun 24 20:05:24 2007 +0200
+++ b/simplify/ast.py	Sun Jun 24 20:06:07 2007 +0200
@@ -85,12 +85,24 @@
 
         self.visitor = self
 
-    def process(self, node, name):
-        result = self.dispatch(node, name)
+    def process(self, module, name):
+
+        """
+        Process the 'module' having the given 'name'. Return the simplified node
+        representing the 'module'.
+        """
+
+        result = self.dispatch(module, name)
         result.simplifier = self
         return result
 
     def dispatch_or_none(self, node, *args):
+
+        """
+        Dispatch to a handler for 'node', returning the result, or if 'node' is
+        None then return a node which loads None in the simplified program.
+        """
+
         if node is not None:
             return self.dispatch(node, *args)
         else: