Update pydocs.

* python/mailutils/__init__.py: Update pydocs.
* python/mailutils/mailbox.py: Likewise.
* python/mailutils/mailcap.py: Likewise.
* python/mailutils/registrar.py: Likewise.
* python/mailutils/sieve.py: Likewise.

@@ -16,6 +16,28 @@
 #  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 #  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 #  MA 02110-1301 USA
 #  MA 02110-1301 USA
 
 
+"""
+A Python interface to Mailutils framework.
+
+GNU Mailutils is a rich and powerful protocol-independent mail
+framework.  It contains a series of useful mail libraries, clients,
+and servers.  These are the primary mail utilities for the GNU system.
+The central library is capable of handling electronic mail in various
+mailbox formats and protocols, both local and remote.  Specifically,
+this project contains a POP3 server, an IMAP4 server, and a Sieve mail
+filter. It also provides a POSIX `mailx' client, and a collection of
+other handy tools.
+
+This software is part of the GNU Project and belongs to the Free
+Software Foundation. All libraries are licensed using the GNU LGPL.
+The documentation is licensed under the GNU FDL, and everything else
+is licensed using the GNU GPL.
+
+See http://www.gnu.org/software/mailutils/ for more information about
+GNU Mailutils.
+
+"""
+
 __all__ = [
 __all__ = [
     "error",
     "error",
     "address",
     "address",

@@ -28,7 +28,19 @@ from mailutils.error import MailboxError
 
 
 class MailboxBase:
 class MailboxBase:
     def open (self, mode = 0):
     def open (self, mode = 0):
-        """Open the connection."""
+        """Open the connection.
+
+        'mode' may be a string, consisting of the characters described
+        below, giving the access mode for the mailbox.
+
+        mode   Meaning
+        -------------------------------------------------------- 
+        r      Open for reading.
+        w      Open for writing.
+        a      Open for appending to the end of the mailbox.
+        c      Create the mailbox if it does not exist.
+
+        """
         if isinstance (mode, types.StringType):
         if isinstance (mode, types.StringType):
             from mailutils import stream
             from mailutils import stream
             flags = 0
             flags = 0
@@ -84,14 +96,14 @@ class MailboxBase:
         return unseen
         return unseen
 
 
     def get_message (self, msgno):
     def get_message (self, msgno):
-        """Retrieve message number MSGNO."""
+        """Retrieve message number 'msgno'."""
         status, c_msg = mailbox.get_message (self.mbox, msgno)
         status, c_msg = mailbox.get_message (self.mbox, msgno)
         if status:
         if status:
             raise MailboxError (status)
             raise MailboxError (status)
         return message.Message (c_msg)
         return message.Message (c_msg)
 
 
     def append_message (self, msg):
     def append_message (self, msg):
-        """Append MSG to the mailbox."""
+        """Append 'msg' to the mailbox."""
         status = mailbox.append_message (self.mbox, msg.msg)
         status = mailbox.append_message (self.mbox, msg.msg)
         if status:
         if status:
             raise MailboxError (status)
             raise MailboxError (status)
@@ -135,19 +147,21 @@ class MailboxBase:
         return size
         return size
 
 
     def get_folder (self):
     def get_folder (self):
-        """Get the FOLDER."""
+        """Get the Folder object."""
         status, fld = mailbox.get_folder (self.mbox)
         status, fld = mailbox.get_folder (self.mbox)
         if status:
         if status:
             raise MailboxError (status)
             raise MailboxError (status)
         return folder.Folder (fld)
         return folder.Folder (fld)
 
 
     def get_debug (self):
     def get_debug (self):
+        """Get the Debug object."""
         status, dbg = mailbox.get_debug (self.mbox)
         status, dbg = mailbox.get_debug (self.mbox)
         if status:
         if status:
             raise MailboxError (status)
             raise MailboxError (status)
         return debug.Debug (dbg)
         return debug.Debug (dbg)
 
 
     def get_url (self):
     def get_url (self):
+        """Get the Url object."""
         status, u = mailbox.get_url (self.mbox)
         status, u = mailbox.get_url (self.mbox)
         if status:
         if status:
             raise MailboxError (status)
             raise MailboxError (status)
@@ -206,6 +220,17 @@ class Mailbox (MailboxBase):
 
 
 class MailboxDefault (MailboxBase):
 class MailboxDefault (MailboxBase):
     def __init__ (self, name = None):
     def __init__ (self, name = None):
+        """MailboxDefault creates a Mailbox object for the supplied
+        mailbox 'name'. Before creating, the name is expanded using
+        the rules below:
+
+        %           --> system mailbox for the real uid
+        %user       --> system mailbox for the given user
+        ~/file      --> /home/user/file
+        ~user/file  --> /home/user/file
+        +file       --> /home/user/Mail/file
+        =file       --> /home/user/Mail/file
+        """
         self.mbox = mailbox.MailboxType ()
         self.mbox = mailbox.MailboxType ()
         status = mailbox.create_default (self.mbox, name)
         status = mailbox.create_default (self.mbox, name)
         if status:
         if status:

@@ -59,7 +59,7 @@ class Mailcap:
         return count
         return count
 
 
     def get_entry (self, item):
     def get_entry (self, item):
-        """Return in MailcapEntry the mailcap entry of ITEM."""
+        """Return in MailcapEntry the mailcap entry of 'item'."""
         status, entry = mailcap.get_entry (self.mc, item)
         status, entry = mailcap.get_entry (self.mc, item)
         if status:
         if status:
             raise MailcapError (status)
             raise MailcapError (status)

@@ -22,6 +22,27 @@ import types
 from mailutils.c_api import registrar
 from mailutils.c_api import registrar
 
 
 def register_format (name = None):
 def register_format (name = None):
+    """Register desired mailutils 'name' format.
+
+    A list or tuple of strings can be given.
+    Each element must be one of the following strings:
+
+    Argument             Meaning
+    -------------------------------------------------------------- 
+    'mbox'               Regular UNIX mbox format
+    'mh'                 MH mailbox format
+    'maildir'            Maildir mailbox format
+    'pop'                POP mailbox format
+    'pops'               POPS mailbox format
+    'imap'               IMAP mailbox format
+    'imaps'              IMAPS mailbox format
+    'sendmail'           sendmail mailer format
+    'smtp'               SMTP mailer format
+
+    If called without arguments, the function registers all available
+    formats.
+
+    """
     if name == None:
     if name == None:
         registrar.register_format ()
         registrar.register_format ()
     elif isinstance (name, types.TupleType) \
     elif isinstance (name, types.TupleType) \

@@ -53,7 +53,7 @@ class Machine:
             raise SieveMachineError (status)
             raise SieveMachineError (status)
 
 
     def compile (self, name):
     def compile (self, name):
-        """Compile the sieve script from the file NAME."""
+        """Compile the sieve script from the file 'name'."""
         status = sieve.compile (self.mach, name)
         status = sieve.compile (self.mach, name)
         if status:
         if status:
             raise SieveMachineError (status)
             raise SieveMachineError (status)
@@ -73,7 +73,7 @@ class Machine:
 
 
     def message (self, msg):
     def message (self, msg):
         """Execute the code from the given instance of sieve machine
         """Execute the code from the given instance of sieve machine
-        over the MSG."""
+        over the 'msg'."""
         status = sieve.message (self.mach, msg.msg)
         status = sieve.message (self.mach, msg.msg)
         if status:
         if status:
             raise SieveMachineError (status)
             raise SieveMachineError (status)