Index: Lib/UserDict.py
===================================================================
--- Lib/UserDict.py	(revision 61014)
+++ Lib/UserDict.py	(working copy)
@@ -1,6 +1,15 @@
-"""A more or less complete user-defined wrapper around dictionary objects."""
+"""User-defined classes to support implementation of dictionary-like objects"""
 
 class UserDict:
+    """A more or less complete user-defined wrapper around dictionary objects
+
+
+    Classes derived from UserDict behave subtly differenty from those
+    derived from built-in dict. For example, overriding
+    UserDict.__getitem__() changes behavior of get() and setdefault() but
+    not has_key() while overriding a dict method does not affect any
+    other method. For a more consistent behavior see DictMixin class.   
+    """
     def __init__(self, dict=None, **kwargs):
         self.data = {}
         if dict is not None:
@@ -80,13 +89,31 @@
         return iter(self.data)
 
 class DictMixin:
-    # Mixin defining all dictionary methods for classes that already have
-    # a minimum dictionary interface including getitem, setitem, delitem,
-    # and keys. Without knowledge of the subclass constructor, the mixin
-    # does not define __init__() or copy().  In addition to the four base
-    # methods, progressively more efficiency comes with defining
-    # __contains__(), __iter__(), and iteritems().
+    """Mixin defining all dictionary methods.
 
+    Base classes must already have a minimum dictionary interface
+    including getitem(), setitem(), delitem(), and keys(). Without knowledge
+    of the subclass constructor, the mixin does not define __init__()
+    or copy().  In addition to the four base methods, progressively
+    more efficiency comes with defining __contains__(), __iter__(),
+    and iteritems().
+
+    The dictionary methods are implemented in four levels where higher
+    level methods call lower levels:
+
+    First level: __getitem__(), __setitem__(), __delitem__(),
+      and keys(). Must be implemented in the base class.
+
+    Second level: __iter__(), has_key(), clear(), setdefault(), pop(),
+      get(), and __len__().
+
+    Third level: __contains__(), iteritems(), and iterkeys().
+
+    Fourth level: itervalues(), values(), items(), popitem(), update(),
+      and __cmp__().
+
+    """
+
     # second level definitions support higher levels
     def __iter__(self):
         for k in self.keys():