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.

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()"""

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

Lib/binhex.py

@@ -1,4 +1,4 @@
-"""binhex - Macintosh binhex compression/decompression
+"""Macintosh binhex compression/decompression.
 
 easy interface:
 binhex(inputfilename, outputfilename)

Lib/copy.py

@@ -1,6 +1,4 @@
-"""\
-Generic (shallow and deep) copying operations
-=============================================
+"""Generic (shallow and deep) copying operations.
 
 Interface summary:
 

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
 

Lib/dospath.py

@@ -1,4 +1,4 @@
-"""Module 'dospath' -- common operations on DOS pathnames"""
+"""Common operations on DOS pathnames."""
 
 import os
 import stat

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

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

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()

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."""
 

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 *

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

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

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

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.)
 

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

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

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

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.
 """
 

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