Patch 560023 adding docstrings. 2.2 Candidate (after verifying modules were not updated after 2.2).

Lib/formatter.py

@@ -27,6 +27,15 @@ AS_IS = None
 
 
 class NullFormatter:
+    """A formatter which does nothing.
+
+    If the writer parameter is omitted, a NullWriter instance is created.
+    No methods of the writer are called by NullFormatter instances.
+
+    Implementations should inherit from this class if implementing a writer
+    interface but don't need to inherit any implementation.
+
+    """
 
     def __init__(self, writer=None):
         if not writer:
@@ -52,6 +61,13 @@ class NullFormatter:
 
 
 class AbstractFormatter:
+    """The standard formatter.
+
+    This implementation has demonstrated wide applicability to many writers,
+    and may be used directly in most circumstances.  It has been used to
+    implement a full-featured World Wide Web browser.
+
+    """
 
     #  Space handling policy:  blank spaces at the boundary between elements
     #  are handled by the outermost context.  "Literal" data is not checked
@@ -283,7 +299,13 @@ class AbstractFormatter:
 
 
 class NullWriter:
-    """Minimal writer interface to use in testing & inheritance."""
+    """Minimal writer interface to use in testing & inheritance.
+
+    A writer which only provides the interface definition; no actions are
+    taken on any methods.  This should be the base class for all writers
+    which do not need to inherit any implementation methods.
+
+    """
     def __init__(self): pass
     def flush(self): pass
     def new_alignment(self, align): pass
@@ -300,6 +322,12 @@ class NullWriter:
 
 
 class AbstractWriter(NullWriter):
+    """A writer which can be used in debugging formatters, but not much else.
+
+    Each method simply announces itself by printing its name and
+    arguments on standard output.
+
+    """
 
     def new_alignment(self, align):
         print "new_alignment(%s)" % `align`
@@ -336,6 +364,13 @@ class AbstractWriter(NullWriter):
 
 
 class DumbWriter(NullWriter):
+    """Simple writer class which writes output on the file object passed in
+    as the file parameter or, if file is omitted, on standard output.  The
+    output is simply word-wrapped to the number of columns specified by
+    the maxcol parameter.  This class is suitable for reflowing a sequence
+    of paragraphs.
+
+    """
 
     def __init__(self, file=None, maxcol=72):
         self.file = file or sys.stdout