Typo corrections, docstrings, naming

traitlets/traitlets.py

@@ -547,8 +547,12 @@ def tag(self, **metadata):
 # The HasTraits implementation
 #-----------------------------------------------------------------------------
 
-class _CbWrapper(object):
+class _CallbackWrapper(object):
+    """An object adapting a on_trait_change callback into an observe callback.
     
+    The comparison operator __eq__ is implemented to enable removal of wrapped
+    callbacks.
+    """ 
 
     def __init__(self, cb):
         if callable(cb):
@@ -563,13 +567,13 @@ def __init__(self, cb):
 
     def __eq__(self, other):
         # The wrapper is equal to the wrapped element
-        if isinstance(other, _CbWrapper):
+        if isinstance(other, _CallbackWrapper):
             return self.cb == other.cb
         else:
             return self.cb == other
 
     def __call__(self, change):
-        # The wrapper is callabled
+        # The wrapper is callable
         if self.nargs == 0:
             self.cb()
         elif self.nargs == 1:
@@ -581,11 +585,11 @@ def __call__(self, change):
         elif self.nargs == 4:
             self.cb(change['name'], change['old'], change['new'], change['object'])
 
-def _cb_wrapper(cb):
-    if isinstance(cb, _CbWrapper):
+def _callback_wrapper(cb):
+    if isinstance(cb, _CallbackWrapper):
         return cb
     else:
-        return _CbWrapper(cb)
+        return _CallbackWrapper(cb)
 
 
 
@@ -630,6 +634,13 @@ class dict to the newly created class ``cls``.
 
 
 def observe(*names):
+    """ A decorator which can be used to observe members on a class.
+
+    Parameters
+    ----------
+    *names
+        The str names of the attributes to observe on the object.
+    """
     return ObserveHandler(names)
 
 
@@ -762,7 +773,7 @@ def _notify_trait(self, name, old_value, new_value):
         else:
             warn("_[traitname]_changed change handlers are deprecated: use observe instead", 
                  DeprecationWarning, stacklevel=2)
-            callables.append(_cb_wrapper(cb))
+            callables.append(_callback_wrapper(cb))
 
         # Call them all now
         for c in callables:
@@ -771,8 +782,8 @@ def _notify_trait(self, name, old_value, new_value):
                 # Bound methods have an additional 'self' argument.
                 offset = -1 if isinstance(c, types.MethodType) else 0
 
-                if isinstance(c, _CbWrapper):
-                    # _CbWrappers are not compatible with getargspec and have one argument
+                if isinstance(c, _CallbackWrapper):
+                    # _CallbackWrappers are not compatible with getargspec and have one argument
                     nargs = 1
                 else:
                     nargs = len(getargspec(c)[0]) + offset
@@ -831,7 +842,7 @@ def on_trait_change(self, handler, name=None, remove=False):
         """
         warn("on_trait_change is deprecated: use observe instead",
              DeprecationWarning, stacklevel=2)
-        self.observe(_cb_wrapper(handler), name=name, remove=remove)
+        self.observe(_callback_wrapper(handler), name=name, remove=remove)
 
     def observe(self, handler, name=None, remove=False):
         """Setup a handler to be called when a trait changes.
@@ -847,14 +858,14 @@ def observe(self, handler, name=None, remove=False):
                 - object : the HasTraits instance
                 - old : the old value of the modified trait attribute
                 - new : the new value of the modified trait attribute
-                - name : the name ofthe modified trait attribute.
+                - name : the name of the modified trait attribute.
         name : list, str, None
             If None, the handler will apply to all traits.  If a list
             of str, handler will apply to all names in the list.  If a
             str, the handler will apply just to that name.
         remove : bool
             If False (the default), then install the handler.  If True
-            then unintall it.
+            then uninstall it.
         """
         if remove:
             names = parse_notifier_name(name)