More trivial comment -> docstring transformations by Ka-Ping Yee,

who writes:

Here is batch 2, as a big collection of CVS context diffs.
Along with moving comments into docstrings, i've added a
couple of missing docstrings and attempted to make sure more
module docstrings begin with a one-line summary.

I did not add docstrings to the methods in profile.py for
fear of upsetting any careful optimizations there, though
i did move class documentation into class docstrings.

The convention i'm using is to leave credits/version/copyright
type of stuff in # comments, and move the rest of the descriptive
stuff about module usage into module docstrings.  Hope this is
okay.

Lib/posixfile.py

@@ -1,64 +1,61 @@
-#
-# Start of posixfile.py
-#
+"""Extended file operations available in POSIX.
 
-#
-# Extended file operations
-#
-# f = posixfile.open(filename, [mode, [bufsize]])
-#       will create a new posixfile object
-#
-# f = posixfile.fileopen(fileobject)
-#       will create a posixfile object from a builtin file object
-#
-# f.file()
-#       will return the original builtin file object
-#
-# f.dup()
-#       will return a new file object based on a new filedescriptor
-#
-# f.dup2(fd)
-#       will return a new file object based on the given filedescriptor
-#
-# f.flags(mode)
-#       will turn on the associated flag (merge)
-#       mode can contain the following characters:
-#
-#   (character representing a flag)
-#       a       append only flag
-#       c       close on exec flag
-#       n       no delay flag
-#       s       synchronization flag
-#   (modifiers)
-#       !       turn flags 'off' instead of default 'on'
-#       =       copy flags 'as is' instead of default 'merge'
-#       ?       return a string in which the characters represent the flags
-#               that are set
-#
-#       note: - the '!' and '=' modifiers are mutually exclusive.
-#             - the '?' modifier will return the status of the flags after they
-#               have been changed by other characters in the mode string
-#
-# f.lock(mode [, len [, start [, whence]]])
-#       will (un)lock a region
-#       mode can contain the following characters:
-#
-#   (character representing type of lock)
-#       u       unlock
-#       r       read lock
-#       w       write lock
-#   (modifiers)
-#       |       wait until the lock can be granted
-#       ?       return the first lock conflicting with the requested lock
-#               or 'None' if there is no conflict. The lock returned is in the
-#               format (mode, len, start, whence, pid) where mode is a
-#               character representing the type of lock ('r' or 'w')
-#
-#       note: - the '?' modifier prevents a region from being locked; it is
-#               query only
-#
+f = posixfile.open(filename, [mode, [bufsize]])
+      will create a new posixfile object
+
+f = posixfile.fileopen(fileobject)
+      will create a posixfile object from a builtin file object
+
+f.file()
+      will return the original builtin file object
+
+f.dup()
+      will return a new file object based on a new filedescriptor
+
+f.dup2(fd)
+      will return a new file object based on the given filedescriptor
+
+f.flags(mode)
+      will turn on the associated flag (merge)
+      mode can contain the following characters:
+
+  (character representing a flag)
+      a       append only flag
+      c       close on exec flag
+      n       no delay flag
+      s       synchronization flag
+  (modifiers)
+      !       turn flags 'off' instead of default 'on'
+      =       copy flags 'as is' instead of default 'merge'
+      ?       return a string in which the characters represent the flags
+              that are set
+
+      note: - the '!' and '=' modifiers are mutually exclusive.
+            - the '?' modifier will return the status of the flags after they
+              have been changed by other characters in the mode string
+
+f.lock(mode [, len [, start [, whence]]])
+      will (un)lock a region
+      mode can contain the following characters:
+
+  (character representing type of lock)
+      u       unlock
+      r       read lock
+      w       write lock
+  (modifiers)
+      |       wait until the lock can be granted
+      ?       return the first lock conflicting with the requested lock
+              or 'None' if there is no conflict. The lock returned is in the
+              format (mode, len, start, whence, pid) where mode is a
+              character representing the type of lock ('r' or 'w')
+
+      note: - the '?' modifier prevents a region from being locked; it is
+              query only
+"""
 
 class _posixfile_:
+    """File wrapper class that provides extra POSIX file routines."""
+
     states = ['open', 'closed']
 
     #
@@ -215,13 +212,12 @@ class _posixfile_:
                 else:
                     return 'w', l_len, l_start, l_whence, l_pid
 
-#
-# Public routine to obtain a posixfile object
-#
 def open(name, mode='r', bufsize=-1):
+    """Public routine to open a file as a posixfile object."""
     return _posixfile_().open(name, mode, bufsize)
 
 def fileopen(file):
+    """Public routine to get a posixfile object from a Python file object."""
     return _posixfile_().fileopen(file)
 
 #