The third and final doc-string sweep by Ka-Ping Yee.

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/quopri.py

@@ -1,25 +1,34 @@
 #! /usr/bin/env python
 
-# Conversions to/from quoted-printable transport encoding as per RFC-1521
+"""Conversions to/from quoted-printable transport encoding as per RFC-1521."""
+
 # (Dec 1991 version).
 
 ESCAPE = '='
 MAXLINESIZE = 76
 HEX = '0123456789ABCDEF'
 
 def needsquoting(c, quotetabs):
+	"""Decide whether a particular character needs to be quoted.
+
+	The 'quotetabs' flag indicates whether tabs should be quoted."""
 	if c == '\t':
 		return not quotetabs
 	return c == ESCAPE or not(' ' <= c <= '~')
 
 def quote(c):
+	"""Quote a single character."""
 	if c == ESCAPE:
 		return ESCAPE * 2
 	else:
 		i = ord(c)
 		return ESCAPE + HEX[i/16] + HEX[i%16]
 
 def encode(input, output, quotetabs):
+	"""Read 'input', apply quoted-printable encoding, and write to 'output'.
+
+	'input' and 'output' are files with readline() and write() methods.
+	The 'quotetabs' flag indicates whether tabs should be quoted."""
 	while 1:
 		line = input.readline()
 		if not line: break
@@ -42,6 +51,9 @@ def encode(input, output, quotetabs):
 			output.write(new + '\n')
 
 def decode(input, output):
+	"""Read 'input', apply quoted-printable decoding, and write to 'output'.
+
+	'input' and 'output' are files with readline() and write() methods."""
 	new = ''
 	while 1:
 		line = input.readline()
@@ -73,9 +85,11 @@ def decode(input, output):
 		output.write(new)
 
 def ishex(c):
+	"""Return true if the character 'c' is a hexadecimal digit."""
 	return '0' <= c <= '9' or 'a' <= c <= 'f' or 'A' <= c <= 'F'
 
 def unhex(s):
+	"""Get the integer value of a hexadecimal number."""
 	bits = 0
 	for c in s:
 		if '0' <= c <= '9':

Lib/random.py

@@ -1,23 +1,24 @@
-#	R A N D O M   V A R I A B L E   G E N E R A T O R S
-#
-#	distributions on the real line:
-#	------------------------------
-#	       normal (Gaussian)
-#	       lognormal
-#	       negative exponential
-#	       gamma
-#	       beta
-#
-#	distributions on the circle (angles 0 to 2pi)
-#	---------------------------------------------
-#	       circular uniform
-#	       von Mises
-
-# Translated from anonymously contributed C/C++ source.
-
-# Multi-threading note: the random number generator used here is not
-# thread-safe; it is possible that two calls return the same random
-# value.  See whrandom.py for more info.
+"""Random variable generators.
+
+    distributions on the real line:
+    ------------------------------
+           normal (Gaussian)
+           lognormal
+           negative exponential
+           gamma
+           beta
+
+    distributions on the circle (angles 0 to 2pi)
+    ---------------------------------------------
+           circular uniform
+           von Mises
+
+Translated from anonymously contributed C/C++ source.
+
+Multi-threading note: the random number generator used here is not
+thread-safe; it is possible that two calls return the same random
+value.  See whrandom.py for more info.
+"""
 
 import whrandom
 from whrandom import random, uniform, randint, choice, randrange # For export!

Lib/regex_syntax.py

@@ -1,5 +1,11 @@
-# These bits are passed to regex.set_syntax() to choose among
-# alternative regexp syntaxes.
+"""Constants for selecting regexp syntaxes for the obsolete regex module.
+
+This module is only for backward compatibility.  "regex" has now
+been replaced by the new regular expression module, "re".
+
+These bits are passed to regex.set_syntax() to choose among
+alternative regexp syntaxes.
+"""
 
 # 1 means plain parentheses serve as grouping, and backslash
 #   parentheses are needed for literal searching.

Lib/regsub.py

@@ -1,10 +1,14 @@
-# Regular expression subroutines:
-# sub(pat, repl, str): replace first occurrence of pattern in string
-# gsub(pat, repl, str): replace all occurrences of pattern in string
-# split(str, pat, maxsplit): split string using pattern as delimiter
-# splitx(str, pat, maxsplit): split string using pattern as delimiter plus
-#			      return delimiters
+"""Regexp-based split and replace using the obsolete regex module.
 
+This module is only for backward compatibility.  These operations
+are now provided by the new regular expression module, "re".
+
+sub(pat, repl, str):        replace first occurrence of pattern in string
+gsub(pat, repl, str):       replace all occurrences of pattern in string
+split(str, pat, maxsplit):  split string using pattern as delimiter
+splitx(str, pat, maxsplit): split string using pattern as delimiter plus
+                            return delimiters
+"""
 
 import regex
 

Lib/repr.py

@@ -1,4 +1,4 @@
-# Redo the `...` (representation) but with limits on most sizes.
+"""Redo the `...` (representation) but with limits on most sizes."""
 
 import string
 

Lib/sgmllib.py

@@ -1,4 +1,4 @@
-# A parser for SGML, using the derived class as static DTD.
+"""A parser for SGML, using the derived class as a static DTD."""
 
 # XXX This only supports those SGML features used by HTML.
 

Lib/shlex.py

@@ -1,3 +1,5 @@
+"""A lexical analyzer class for simple shell-like syntaxes."""
+
 # Module and documentation by Eric S. Raymond, 21 Dec 1998 
 
 import sys

Lib/shutil.py

@@ -1,4 +1,4 @@
-"""Utility functions for copying files.
+"""Utility functions for copying files and directory trees.
 
 XXX The functions here don't copy the resource fork or other metadata on Mac.
 

Lib/stat.py

@@ -1,10 +1,8 @@
-# Module 'stat'
-#
-# Defines constants and functions for interpreting stat/lstat struct
-# as returned by os.stat() and os.lstat() (if it exists).
-#
-# Suggested usage: from stat import *
-#
+"""Constants/functions for interpreting results of os.stat() and os.lstat().
+
+Suggested usage: from stat import *
+"""
+
 # XXX Strictly spoken, this module may have to be adapted for each POSIX
 # implementation; in practice, however, the numeric constants used by
 # stat() are almost universal (even for stat() emulations on non-UNIX

Lib/statcache.py

@@ -1,7 +1,6 @@
-# Module 'statcache'
-#
-# Maintain a cache of file stats.
-# There are functions to reset the cache or to selectively remove items.
+"""Maintain a cache of file stats.
+There are functions to reset the cache or to selectively remove items.
+"""
 
 import os
 from stat import *
@@ -12,42 +11,37 @@
 cache = {}
 
 
-# Stat a file, possibly out of the cache.
-#
 def stat(path):
+	"""Stat a file, possibly out of the cache."""
 	if cache.has_key(path):
 		return cache[path]
 	cache[path] = ret = os.stat(path)
 	return ret
 
 
-# Reset the cache completely.
-#
 def reset():
+	"""Reset the cache completely."""
 	global cache
 	cache = {}
 
 
-# Remove a given item from the cache, if it exists.
-#
 def forget(path):
+	"""Remove a given item from the cache, if it exists."""
 	if cache.has_key(path):
 		del cache[path]
 
 
-# Remove all pathnames with a given prefix.
-#
 def forget_prefix(prefix):
+	"""Remove all pathnames with a given prefix."""
 	n = len(prefix)
 	for path in cache.keys():
 		if path[:n] == prefix:
 			del cache[path]
 
 
-# Forget about a directory and all entries in it, but not about
-# entries in subdirectories.
-#
 def forget_dir(prefix):
+	"""Forget about a directory and all entries in it, but not about
+	entries in subdirectories."""
 	if prefix[-1:] == '/' and prefix <> '/':
 		prefix = prefix[:-1]
 	forget(prefix)
@@ -62,19 +56,17 @@ def forget_dir(prefix):
 				del cache[path]
 
 
-# Remove all pathnames except with a given prefix.
-# Normally used with prefix = '/' after a chdir().
-#
 def forget_except_prefix(prefix):
+	"""Remove all pathnames except with a given prefix.
+	Normally used with prefix = '/' after a chdir()."""
 	n = len(prefix)
 	for path in cache.keys():
 		if path[:n] <> prefix:
 			del cache[path]
 
 
-# Check for directory.
-#
 def isdir(path):
+	"""Check for directory."""
 	try:
 		st = stat(path)
 	except os.error:

Lib/statvfs.py

@@ -1,8 +1,4 @@
-# Module 'statvfs'
-#
-# Defines constants for interpreting statvfs struct as returned
-# by os.statvfs() and os.fstatvfs() (if they exist).
-#
+"""Constants for interpreting the results of os.statvfs() and os.fstatvfs()."""
 
 # Indices for statvfs struct members in the tuple returned by
 # os.statvfs() and os.fstatvfs().

Lib/string.py

@@ -1,11 +1,9 @@
-# module 'string' -- A collection of string operations
+"""A collection of string operations (most are no longer used in Python 1.6).
 
-# Warning: most of the code you see here isn't normally used nowadays.  With
-# Python 1.6, many of these functions are implemented as methods on the
-# standard string object. They used to be implemented by a built-in module
-# called strop, but strop is now obsolete itself.
-
-"""Common string manipulations.
+Warning: most of the code you see here isn't normally used nowadays.  With
+Python 1.6, many of these functions are implemented as methods on the
+standard string object. They used to be implemented by a built-in module
+called strop, but strop is now obsolete itself.
 
 Public module variables: