Actually, the previous batch's comment should have been different;

*this* set of patches is Ka-Ping's final sweep:

The attached patches update the standard library so that all modules
have docstrings beginning with one-line summaries.

A new docstring was added to formatter.  The docstring for os.py
was updated to mention nt, os2, ce in addition to posix, dos, mac.

20 files changed, 99 insertions, 48 deletions

diff --git a/Lib/asynchat.py b/Lib/asynchat.py
index e725a2b..8b2f59f 100644
--- a/Lib/asynchat.py
+++ b/Lib/asynchat.py
@@ -25,28 +25,31 @@
 # CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 # ======================================================================
 
+"""A class supporting chat-style (command/response) protocols.
+
+This class adds support for 'chat' style protocols - where one side
+sends a 'command', and the other sends a response (examples would be
+the common internet protocols - smtp, nntp, ftp, etc..).
+
+The handle_read() method looks at the input stream for the current
+'terminator' (usually '\r\n' for single-line responses, '\r\n.\r\n'
+for multi-line output), calling self.found_terminator() on its
+receipt.
+
+for example:
+Say you build an async nntp client using this class.  At the start
+of the connection, you'll have self.terminator set to '\r\n', in
+order to process the single-line greeting.  Just before issuing a
+'LIST' command you'll set it to '\r\n.\r\n'.  The output of the LIST
+command will be accumulated (using your own 'collect_incoming_data'
+method) up to the terminator, and then control will be returned to
+you - by calling your self.found_terminator() method.
+"""
+
 import socket
 import asyncore
 import string
 
-# This class adds support for 'chat' style protocols - where one side
-# sends a 'command', and the other sends a response (examples would be
-# the common internet protocols - smtp, nntp, ftp, etc..).
-
-# The handle_read() method looks at the input stream for the current
-# 'terminator' (usually '\r\n' for single-line responses, '\r\n.\r\n'
-# for multi-line output), calling self.found_terminator() on its
-# receipt.
-
-# for example:
-# Say you build an async nntp client using this class.  At the start
-# of the connection, you'll have self.terminator set to '\r\n', in
-# order to process the single-line greeting.  Just before issuing a
-# 'LIST' command you'll set it to '\r\n.\r\n'.  The output of the LIST
-# command will be accumulated (using your own 'collect_incoming_data'
-# method) up to the terminator, and then control will be returned to
-# you - by calling your self.found_terminator() method
-
 class async_chat (asyncore.dispatcher):
 	"""This is an abstract class.  You must derive from this class, and add
 	the two methods collect_incoming_data() and found_terminator()"""
diff --git a/Lib/asyncore.py b/Lib/asyncore.py
index 07b9fc3..8e11d76 100644
--- a/Lib/asyncore.py
+++ b/Lib/asyncore.py
@@ -25,6 +25,27 @@
 # CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 # ======================================================================
 
+"""Basic infrastructure for asynchronous socket service clients and servers.
+
+There are only two ways to have a program on a single processor do "more
+than one thing at a time".  Multi-threaded programming is the simplest and 
+most popular way to do it, but there is another very different technique,
+that lets you have nearly all the advantages of multi-threading, without
+actually using multiple threads. it's really only practical if your program
+is largely I/O bound. If your program is CPU bound, then pre-emptive
+scheduled threads are probably what you really need. Network servers are
+rarely CPU-bound, however. 
+
+If your operating system supports the select() system call in its I/O 
+library (and nearly all do), then you can use it to juggle multiple
+communication channels at once; doing other work while your I/O is taking
+place in the "background."  Although this strategy can seem strange and
+complex, especially at first, it is in many ways easier to understand and
+control than multi-threaded programming. The module documented here solves
+many of the difficult problems for you, making the task of building
+sophisticated high-performance network servers and clients a snap. 
+"""
+
 import select
 import socket
 import string
diff --git a/Lib/binhex.py b/Lib/binhex.py
index 3fc7234..db6a7ef 100644
--- a/Lib/binhex.py
+++ b/Lib/binhex.py
@@ -1,4 +1,4 @@
-"""binhex - Macintosh binhex compression/decompression
+"""Macintosh binhex compression/decompression.
 
 easy interface:
 binhex(inputfilename, outputfilename)
diff --git a/Lib/copy.py b/Lib/copy.py
index 2d9de3c..e4679de 100644
--- a/Lib/copy.py
+++ b/Lib/copy.py
@@ -1,6 +1,4 @@
-"""\
-Generic (shallow and deep) copying operations
-=============================================
+"""Generic (shallow and deep) copying operations.
 
 Interface summary:
 
diff --git a/Lib/dircache.py b/Lib/dircache.py
index b0a3665..a35e16d 100644
--- a/Lib/dircache.py
+++ b/Lib/dircache.py
@@ -1,6 +1,8 @@
-"""Return a sorted list of the files in a directory, using a cache
-to avoid reading the directory more often than necessary.
-Also contains a subroutine to append slashes to directories."""
+"""Read and cache directory listings.
+
+The listdir() routine returns a sorted list of the files in a directory,
+using a cache to avoid reading the directory more often than necessary.
+The annotate() routine appends slashes to directories."""
 
 import os
 
diff --git a/Lib/dospath.py b/Lib/dospath.py
index 2ad21f0..4e4be56 100644
--- a/Lib/dospath.py
+++ b/Lib/dospath.py
@@ -1,4 +1,4 @@
-"""Module 'dospath' -- common operations on DOS pathnames"""
+"""Common operations on DOS pathnames."""
 
 import os
 import stat
diff --git a/Lib/formatter.py b/Lib/formatter.py
index 4b340d5..4d6a129 100644
--- a/Lib/formatter.py
+++ b/Lib/formatter.py
@@ -1,3 +1,23 @@
+"""Generic output formatting.
+
+Formatter objects transform an abstract flow of formatting events into
+specific output events on writer objects. Formatters manage several stack
+structures to allow various properties of a writer object to be changed and
+restored; writers need not be able to handle relative changes nor any sort
+of ``change back'' operation. Specific writer properties which may be
+controlled via formatter objects are horizontal alignment, font, and left
+margin indentations. A mechanism is provided which supports providing
+arbitrary, non-exclusive style settings to a writer as well. Additional
+interfaces facilitate formatting events which are not reversible, such as
+paragraph separation. 
+
+Writer objects encapsulate device interfaces. Abstract devices, such as
+file formats, are supported as well as physical devices. The provided
+implementations all work with abstract devices. The interface makes
+available mechanisms for setting the properties which formatter objects
+manage and inserting data into the output. 
+"""
+
 import string
 import sys
 from types import StringType
diff --git a/Lib/ftplib.py b/Lib/ftplib.py
index eee8e5a..94ae880 100644
--- a/Lib/ftplib.py
+++ b/Lib/ftplib.py
@@ -1,4 +1,5 @@
-'''An FTP client class, and some helper functions.
+"""An FTP client class and some helper functions.
+
 Based on RFC 959: File Transfer Protocol
 (FTP), by J. Postel and J. Reynolds
 
@@ -31,7 +32,7 @@ drwxr-xr-x   3 root     wheel        1024 Jan  3  1994 usr
 
 A nice test that reveals some of the network dialogue would be:
 python ftplib.py -d localhost -l -p -l
-'''
+"""
 
 
 import os
diff --git a/Lib/getopt.py b/Lib/getopt.py
index b5fdaed..692b8b9 100644
--- a/Lib/getopt.py
+++ b/Lib/getopt.py
@@ -1,4 +1,4 @@
-"""Module getopt -- Parser for command line options.
+"""Parser for command line options.
 
 This module helps scripts to parse the command line arguments in
 sys.argv.  It supports the same conventions as the Unix getopt()
diff --git a/Lib/gzip.py b/Lib/gzip.py
index ee39169..25278be 100644
--- a/Lib/gzip.py
+++ b/Lib/gzip.py
@@ -1,4 +1,5 @@
-"""This module implements a function that reads and writes a gzipped file.
+"""Functions that read and write gzipped files.
+
 The user of the file doesn't have to worry about the compression,
 but random access is not allowed."""
 
diff --git a/Lib/locale.py b/Lib/locale.py
index d85cabf..9be729d 100644
--- a/Lib/locale.py
+++ b/Lib/locale.py
@@ -1,4 +1,5 @@
-"Support for number formatting using the current locale settings"
+"""Support for number formatting using the current locale settings."""
+
 # Author: Martin von Loewis
 
 from _locale import *
diff --git a/Lib/macurl2path.py b/Lib/macurl2path.py
index 4c43d21..c971eda 100644
--- a/Lib/macurl2path.py
+++ b/Lib/macurl2path.py
@@ -1,5 +1,6 @@
-"""Mac specific module for conversion between pathnames and URLs.
-Do not import directly, use urllib instead."""
+"""Macintosh-specific module for conversion between pathnames and URLs.
+
+Do not import directly; use urllib instead."""
 
 import string
 import urllib
diff --git a/Lib/mimify.py b/Lib/mimify.py
index 354cdb7..20b4d6c 100755
--- a/Lib/mimify.py
+++ b/Lib/mimify.py
@@ -1,6 +1,6 @@
 #! /usr/bin/env python
 
-'''Mimification and unmimification of mail messages.
+"""Mimification and unmimification of mail messages.
 
 Decode quoted-printable parts of a mail message or encode using
 quoted-printable.
@@ -19,7 +19,7 @@ Interactive usage:
 	mimify.py -d [infile [outfile]]
 to encode and decode respectively.  Infile defaults to standard
 input and outfile to standard output.
-'''
+"""
 
 # Configure
 MAXLEN = 200	# if lines longer than this, encode as quoted-printable
diff --git a/Lib/os.py b/Lib/os.py
index 129d4b2..118b619 100644
--- a/Lib/os.py
+++ b/Lib/os.py
@@ -1,14 +1,15 @@
-"""os.py -- either mac, dos or posix depending on what system we're on.
+"""OS routines for Mac, DOS, NT, or Posix depending on what system we're on.
 
 This exports:
-  - all functions from either posix or mac, e.g., os.unlink, os.stat, etc.
-  - os.path is either module posixpath or macpath
-  - os.name is either 'posix' or 'mac'
+  - all functions from posix, nt, dos, os2, mac, or ce, e.g. unlink, stat, etc.
+  - os.path is one of the modules posixpath, ntpath, macpath, or dospath
+  - os.name is 'posix', 'nt', 'dos', 'os2', 'mac', or 'ce'
   - os.curdir is a string representing the current directory ('.' or ':')
   - os.pardir is a string representing the parent directory ('..' or '::')
   - os.sep is the (or a most common) pathname separator ('/' or ':' or '\\')
-  - os.altsep is the alternatte pathname separator (None or '/')
+  - os.altsep is the alternate pathname separator (None or '/')
   - os.pathsep is the component separator used in $PATH etc
+  - os.linesep is the line separator in text files ('\r' or '\n' or '\r\n')
   - os.defpath is the default search path for executables
 
 Programs that import and use 'os' stand a better chance of being
diff --git a/Lib/pdb.py b/Lib/pdb.py
index 3835f03..2e45098 100755
--- a/Lib/pdb.py
+++ b/Lib/pdb.py
@@ -1,6 +1,6 @@
 #! /usr/bin/env python
 
-"""pdb.py -- finally, a Python debugger!"""
+"""A Python debugger."""
 
 # (See pdb.doc for documentation.)
 
diff --git a/Lib/pyclbr.py b/Lib/pyclbr.py
index de3fedc..74b7ff7 100644
--- a/Lib/pyclbr.py
+++ b/Lib/pyclbr.py
@@ -1,4 +1,4 @@
-'''Parse a Python file and retrieve classes and methods.
+"""Parse a Python file and retrieve classes and methods.
 
 Parse enough of a Python file to recognize class and method
 definitions and to find out the superclasses of a class.
@@ -51,7 +51,7 @@ PACKAGE RELATED BUGS
   It can't locate the parent.  It probably needs to have the same
   hairy logic that the import locator already does.  (This logic
   exists coded in Python in the freeze package.)
-''' # ' <-- bow to font lock
+"""
 
 import os
 import sys
diff --git a/Lib/sched.py b/Lib/sched.py
index 147977c..f51d835 100644
--- a/Lib/sched.py
+++ b/Lib/sched.py
@@ -1,4 +1,4 @@
-"""Module sched -- a generally useful event scheduler class
+"""A generally useful event scheduler class.
 
 Each instance of this class manages its own queue.
 No multi-threading is implied; you are supposed to hack that
diff --git a/Lib/smtplib.py b/Lib/smtplib.py
index 1c42233..df8907d 100755
--- a/Lib/smtplib.py
+++ b/Lib/smtplib.py
@@ -1,6 +1,6 @@
 #! /usr/bin/env python
 
-'''SMTP/ESMTP client class.
+"""SMTP/ESMTP client class.
 
 Author: The Dragon De Monsyne <dragondm@integral.org>
 ESMTP support, test code and doc fixes added by
@@ -37,7 +37,7 @@ Example:
   >>> s.getreply()
   (250, "Somebody OverHere <somebody@here.my.org>")
   >>> s.quit()
-'''
+"""
 
 import socket
 import string
diff --git a/Lib/statcache.py b/Lib/statcache.py
index 0d88a9a..b5147c2 100644
--- a/Lib/statcache.py
+++ b/Lib/statcache.py
@@ -1,4 +1,5 @@
-"""Maintain a cache of file stats.
+"""Maintain a cache of stat() information on files.
+
 There are functions to reset the cache or to selectively remove items.
 """
 
diff --git a/Lib/xmllib.py b/Lib/xmllib.py
index dcfe872..16a56b0 100644
--- a/Lib/xmllib.py
+++ b/Lib/xmllib.py
@@ -1,4 +1,5 @@
-# A parser for XML, using the derived class as static DTD.
+"""A parser for XML, using the derived class as static DTD."""
+
 # Author: Sjoerd Mullender.
 
 import re