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

gvanrossum · gvanrossum · commit 4b8c6eaf8b28 · 2000-02-04T15:39:30.000Z
*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.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 @@
 
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 @@
 	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
@@ -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
@@ -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
@@ -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 @@ class MyClass(subpackage.SuperClass):
   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
@@ -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
@@ -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 @@
   >>> 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
@@ -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
@@ -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

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-"""binhex - Macintosh binhex compression/decompression`
	`1`	`+"""Macintosh binhex compression/decompression.`
`2`	`2`
`3`	`3`	`easy interface:`
`4`	`4`	`binhex(inputfilename, outputfilename)`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-"""Module 'dospath' -- common operations on DOS pathnames"""`
	`1`	`+"""Common operations on DOS pathnames."""`
`2`	`2`
`3`	`3`	`import os`
`4`	`4`	`import stat`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-"""Module getopt -- Parser for command line options.`
	`1`	`+"""Parser for command line options.`
`2`	`2`
`3`	`3`	`This module helps scripts to parse the command line arguments in`
`4`	`4`	`sys.argv. It supports the same conventions as the Unix getopt()`