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/mailcap.py b/Lib/mailcap.py
index e19a746..636f2dd 100644
--- a/Lib/mailcap.py
+++ b/Lib/mailcap.py
@@ -9,8 +9,11 @@
def getcaps():
"""Return a dictionary containing the mailcap database.
- The dictionary maps a MIME type (in all lowercase,
- e.g. 'text/plain') to a list of corresponding mailcap entries.
+ The dictionary maps a MIME type (in all lowercase, e.g. 'text/plain')
+ to a list of dictionaries corresponding to mailcap entries. The list
+ collects all the entries for that MIME type from all available mailcap
+ files. Each dictionary contains key-value pairs for that MIME type,
+ where the viewing command is stored with the key "view".
"""
caps = {}
@@ -48,6 +51,14 @@
# Part 2: the parser.
def readmailcapfile(fp):
+ """Read a mailcap file and return a dictionary keyed by MIME type.
+
+ Each MIME type is mapped to an entry consisting of a list of
+ dictionaries; the list will contain more than one such dictionary
+ if a given MIME type appears more than once in the mailcap file.
+ Each dictionary contains key-value pairs for that MIME type, where
+ the viewing command is stored with the key "view".
+ """
caps = {}
while 1:
line = fp.readline()
@@ -78,6 +89,11 @@
return caps
def parseline(line):
+ """Parse one entry in a mailcap file and return a dictionary.
+
+ The viewing command is stored as the value with the key "view",
+ and the rest of the fields produce key-value pairs in the dict.
+ """
fields = []
i, n = 0, len(line)
while i < n:
@@ -104,6 +120,7 @@
return key, fields
def parsefield(line, i, n):
+ """Separate one key-value pair in a mailcap entry."""
start = i
while i < n:
c = line[i]