Backport change to 1.18 adding docstrings

diff --git a/Lib/dumbdbm.py b/Lib/dumbdbm.py
index 920a464d4f3cb97200399283c741b7579891b4ac..c2b79523b4d869becc00658d4fe5d7499b29b3e6 100644 (file)
--- a/Lib/dumbdbm.py
+++ b/Lib/dumbdbm.py
@@ -150,9 +150,21 @@ class _Database:
     def __del__(self):
         if self._index is not None:
             self._commit()
-  
+
 
 
 def open(file, flag=None, mode=0666):
+    """Open the database file, filename, and return corresponding object.
+
+    The flag argument, used to control how the database is opened in the
+    other DBM implementations, is ignored in the dumbdbm module; the
+    database is always opened for update, and will be created if it does
+    not exist.
+
+    The optional mode argument is the UNIX mode of the file, used only when
+    the database has to be created.  It defaults to octal code 0666 (and
+    will be modified by the prevailing umask).
+
+    """
     # flag, mode arguments are currently ignored
     return _Database(file, mode)

diff --git a/Lib/formatter.py b/Lib/formatter.py
index 0607526404ced4d19a05a7ec56068d91e29d3466..75f4718c20fa7dd4931cf12ad94f67de2d5ce5ff 100644 (file)
--- a/Lib/formatter.py
+++ b/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