# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1197330923 -3600
# Node ID 3b4392ceb09a17d27eb179e88bf89523f43ff362
# Parent  1427b21ed257ecfb5c0d333efe7253ad53e78b8d
Improved docstrings.
Added a generic node attribute to instances of the Module class.

diff -r 1427b21ed257 -r 3b4392ceb09a micropython/inspect.py
--- a/micropython/inspect.py	Wed Nov 21 01:30:12 2007 +0100
+++ b/micropython/inspect.py	Tue Dec 11 00:55:23 2007 +0100
@@ -17,6 +17,32 @@
 
 You should have received a copy of the GNU General Public License along with
 this program.  If not, see <http://www.gnu.org/licenses/>.
+
+--------
+
+The central classes in this module are the following:
+
+  * Class
+  * Function
+  * Module
+  * InspectedModule (derived from Module)
+
+All of the above support the Naming interface either explicitly or through
+general conformance, meaning that all can be asked to provide their 'full_name'
+using the method of that name.
+
+Additionally, all of the above also support a dictionary interface in order to
+access names within their defined scopes. Specific methods also exist in order
+to distinguish between certain kinds of attributes:
+
+  * Class: (class|all_class|instance|all)_attributes
+  * Function: parameters, locals
+  * Module: module_attributes
+
+These specific methods are useful in certain situations.
+
+The above classes also provide a 'node' attribute, indicating the AST node where
+each such object is defined.
 """
 
 import compiler.ast
@@ -332,6 +358,8 @@
 
 class Module(NamespaceDict):
 
+    "An inspected module's core details."
+
     def __init__(self, name):
         NamespaceDict.__init__(self)
         self.name = name
@@ -350,6 +378,10 @@
         self.location = None
         self.code_location = None
 
+        # Original location details.
+
+        self.node = None
+
     def full_name(self):
         return self.name
 
@@ -380,7 +412,10 @@
 
 class InspectedModule(ASTVisitor, Module):
 
-    "An inspected module."
+    """
+    An inspected module, providing core details via the Module superclass, but
+    capable of being used as an AST visitor.
+    """
 
     def __init__(self, name, importer=None):
         ASTVisitor.__init__(self)
@@ -411,7 +446,7 @@
 
         "Process the given 'module'."
 
-        self.module = module
+        self.node = self.module = module
         processed = self.dispatch(module)
         if self.has_key("__all__"):
             all = self["__all__"]