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.
diff --git a/Lib/posixfile.py b/Lib/posixfile.py
index ba83b0a..2db37e0 100644
--- a/Lib/posixfile.py
+++ b/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 @@
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)
#