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.

1 files changed, 104 insertions, 103 deletions

diff --git a/Lib/sunau.py b/Lib/sunau.py
index 0ba7dc9..5e8ac32 100644
--- a/Lib/sunau.py
+++ b/Lib/sunau.py
@@ -1,106 +1,107 @@
-# Stuff to parse Sun and NeXT audio files.
-#
-# An audio consists of a header followed by the data.  The structure
-# of the header is as follows.
-#
-#	+---------------+
-#	| magic word    |
-#	+---------------+
-#	| header size   |
-#	+---------------+
-#	| data size     |
-#	+---------------+
-#	| encoding      |
-#	+---------------+
-#	| sample rate   |
-#	+---------------+
-#	| # of channels |
-#	+---------------+
-#	| info          |
-#	|               |
-#	+---------------+
-#
-# The magic word consists of the 4 characters '.snd'.  Apart from the
-# info field, all header fields are 4 bytes in size.  They are all
-# 32-bit unsigned integers encoded in big-endian byte order.
-#
-# The header size really gives the start of the data.
-# The data size is the physical size of the data.  From the other
-# parameter the number of frames can be calculated.
-# The encoding gives the way in which audio samples are encoded.
-# Possible values are listed below.
-# The info field currently consists of an ASCII string giving a
-# human-readable description of the audio file.  The info field is
-# padded with NUL bytes to the header size.
-#
-# Usage.
-#
-# Reading audio files:
-#	f = sunau.open(file, 'r')
-# where file is either the name of a file or an open file pointer.
-# The open file pointer must have methods read(), seek(), and close().
-# When the setpos() and rewind() methods are not used, the seek()
-# method is not  necessary.
-#
-# This returns an instance of a class with the following public methods:
-#	getnchannels()	-- returns number of audio channels (1 for
-#			   mono, 2 for stereo)
-#	getsampwidth()	-- returns sample width in bytes
-#	getframerate()	-- returns sampling frequency
-#	getnframes()	-- returns number of audio frames
-#	getcomptype()	-- returns compression type ('NONE' or 'ULAW')
-#	getcompname()	-- returns human-readable version of
-#			   compression type ('not compressed' matches 'NONE')
-#	getparams()	-- returns a tuple consisting of all of the
-#			   above in the above order
-#	getmarkers()	-- returns None (for compatibility with the
-#			   aifc module)
-#	getmark(id)	-- raises an error since the mark does not
-#			   exist (for compatibility with the aifc module)
-#	readframes(n)	-- returns at most n frames of audio
-#	rewind()	-- rewind to the beginning of the audio stream
-#	setpos(pos)	-- seek to the specified position
-#	tell()		-- return the current position
-#	close()		-- close the instance (make it unusable)
-# The position returned by tell() and the position given to setpos()
-# are compatible and have nothing to do with the actual postion in the
-# file.
-# The close() method is called automatically when the class instance
-# is destroyed.
-#
-# Writing audio files:
-#	f = sunau.open(file, 'w')
-# where file is either the name of a file or an open file pointer.
-# The open file pointer must have methods write(), tell(), seek(), and
-# close().
-#
-# This returns an instance of a class with the following public methods:
-#	setnchannels(n)	-- set the number of channels
-#	setsampwidth(n)	-- set the sample width
-#	setframerate(n)	-- set the frame rate
-#	setnframes(n)	-- set the number of frames
-#	setcomptype(type, name)
-#			-- set the compression type and the
-#			   human-readable compression type
-#	setparams(tuple)-- set all parameters at once
-#	tell()		-- return current position in output file
-#	writeframesraw(data)
-#			-- write audio frames without pathing up the
-#			   file header
-#	writeframes(data)
-#			-- write audio frames and patch up the file header
-#	close()		-- patch up the file header and close the
-#			   output file
-# You should set the parameters before the first writeframesraw or
-# writeframes.  The total number of frames does not need to be set,
-# but when it is set to the correct value, the header does not have to
-# be patched up.
-# It is best to first set all parameters, perhaps possibly the
-# compression type, and then write audio frames using writeframesraw.
-# When all frames have been written, either call writeframes('') or
-# close() to patch up the sizes in the header.
-# The close() method is called automatically when the class instance
-# is destroyed.
+"""Stuff to parse Sun and NeXT audio files.
+
+An audio consists of a header followed by the data.  The structure
+of the header is as follows.
+
+        +---------------+
+        | magic word    |
+        +---------------+
+        | header size   |
+        +---------------+
+        | data size     |
+        +---------------+
+        | encoding      |
+        +---------------+
+        | sample rate   |
+        +---------------+
+        | # of channels |
+        +---------------+
+        | info          |
+        |               |
+        +---------------+
+
+The magic word consists of the 4 characters '.snd'.  Apart from the
+info field, all header fields are 4 bytes in size.  They are all
+32-bit unsigned integers encoded in big-endian byte order.
+
+The header size really gives the start of the data.
+The data size is the physical size of the data.  From the other
+parameter the number of frames can be calculated.
+The encoding gives the way in which audio samples are encoded.
+Possible values are listed below.
+The info field currently consists of an ASCII string giving a
+human-readable description of the audio file.  The info field is
+padded with NUL bytes to the header size.
+
+Usage.
+
+Reading audio files:
+        f = sunau.open(file, 'r')
+where file is either the name of a file or an open file pointer.
+The open file pointer must have methods read(), seek(), and close().
+When the setpos() and rewind() methods are not used, the seek()
+method is not  necessary.
+
+This returns an instance of a class with the following public methods:
+        getnchannels()	-- returns number of audio channels (1 for
+        		   mono, 2 for stereo)
+        getsampwidth()	-- returns sample width in bytes
+        getframerate()	-- returns sampling frequency
+        getnframes()	-- returns number of audio frames
+        getcomptype()	-- returns compression type ('NONE' or 'ULAW')
+        getcompname()	-- returns human-readable version of
+        		   compression type ('not compressed' matches 'NONE')
+        getparams()	-- returns a tuple consisting of all of the
+        		   above in the above order
+        getmarkers()	-- returns None (for compatibility with the
+        		   aifc module)
+        getmark(id)	-- raises an error since the mark does not
+        		   exist (for compatibility with the aifc module)
+        readframes(n)	-- returns at most n frames of audio
+        rewind()	-- rewind to the beginning of the audio stream
+        setpos(pos)	-- seek to the specified position
+        tell()		-- return the current position
+        close()		-- close the instance (make it unusable)
+The position returned by tell() and the position given to setpos()
+are compatible and have nothing to do with the actual postion in the
+file.
+The close() method is called automatically when the class instance
+is destroyed.
+
+Writing audio files:
+        f = sunau.open(file, 'w')
+where file is either the name of a file or an open file pointer.
+The open file pointer must have methods write(), tell(), seek(), and
+close().
+
+This returns an instance of a class with the following public methods:
+        setnchannels(n)	-- set the number of channels
+        setsampwidth(n)	-- set the sample width
+        setframerate(n)	-- set the frame rate
+        setnframes(n)	-- set the number of frames
+        setcomptype(type, name)
+        		-- set the compression type and the
+        		   human-readable compression type
+        setparams(tuple)-- set all parameters at once
+        tell()		-- return current position in output file
+        writeframesraw(data)
+        		-- write audio frames without pathing up the
+        		   file header
+        writeframes(data)
+        		-- write audio frames and patch up the file header
+        close()		-- patch up the file header and close the
+        		   output file
+You should set the parameters before the first writeframesraw or
+writeframes.  The total number of frames does not need to be set,
+but when it is set to the correct value, the header does not have to
+be patched up.
+It is best to first set all parameters, perhaps possibly the
+compression type, and then write audio frames using writeframesraw.
+When all frames have been written, either call writeframes('') or
+close() to patch up the sizes in the header.
+The close() method is called automatically when the class instance
+is destroyed.
+"""
 
 # from <multimedia/audio_filehdr.h>
 AUDIO_FILE_MAGIC = 0x2e736e64