Patch 560023 adding docstrings. 2.2 Candidate (after verifying modules were not updated after 2.2).
diff --git a/Lib/formatter.py b/Lib/formatter.py
index 0607526..75f4718 100644
--- a/Lib/formatter.py
+++ b/Lib/formatter.py
@@ -27,6 +27,15 @@
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 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 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 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 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