Added bugdir and comment modules to Sphinx docs

6 files changed, 55 insertions, 27 deletions

diff --git a/doc/libbe.bugdir.txt b/doc/libbe.bugdir.txt
new file mode 100644
index 0000000..2464ea6
--- /dev/null
+++ b/doc/libbe.bugdir.txt
@@ -0,0 +1,7 @@
+*******************
+:mod:`libbe.bugdir`
+*******************
+
+.. automodule:: libbe.bugdir
+   :members:
+   :undoc-members:
diff --git a/doc/libbe.comment.txt b/doc/libbe.comment.txt
new file mode 100644
index 0000000..6e76f98
--- /dev/null
+++ b/doc/libbe.comment.txt
@@ -0,0 +1,7 @@
+********************
+:mod:`libbe.comment`
+********************
+
+.. automodule:: libbe.comment
+   :members:
+   :undoc-members:
diff --git a/doc/libbe.txt b/doc/libbe.txt
index dd04df1..5d29434 100644
--- a/doc/libbe.txt
+++ b/doc/libbe.txt
@@ -9,4 +9,6 @@
 .. toctree::
    :maxdepth: 2
 
+   libbe.bugdir.txt
    libbe.bug.txt
+   libbe.comment.txt
diff --git a/libbe/bug.py b/libbe/bug.py
index a4b569f..dd68518 100644
--- a/libbe/bug.py
+++ b/libbe/bug.py
@@ -16,7 +16,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-"""Define the Bug class for representing bugs.
+"""Define the :class:`Bug` class for representing bugs.
 """
 
 import copy
@@ -122,7 +122,9 @@ load_status(active_status_def, inactive_status_def)
 
 class Bug (settings_object.SavedSettingsObject):
     """A bug (or issue) is a place to store attributes and attach
-    comments.  In mailing-list terms, a bug is analogous to a thread.
+    :class:`libbe.comment.Comment`\s.  In mailing-list terms, a bug is
+    analogous to a thread.  Bugs are normally stored in
+    :class:`libbe.bugdir.BugDir`\s.
 
     >>> b = Bug()
     >>> print b.status
@@ -716,6 +718,7 @@ def cmp_severity(bug_1, bug_2):
     """
     Compare the severity levels of two bugs, with more severe bugs
     comparing as less.
+
     >>> bugA = Bug()
     >>> bugB = Bug()
     >>> bugA.severity = bugB.severity = "wishlist"
@@ -734,8 +737,9 @@ def cmp_severity(bug_1, bug_2):
 
 def cmp_status(bug_1, bug_2):
     """
-    Compare the status levels of two bugs, with more 'open' bugs
+    Compare the status levels of two bugs, with more "open" bugs
     comparing as less.
+
     >>> bugA = Bug()
     >>> bugB = Bug()
     >>> bugA.status = bugB.status = "open"
@@ -755,9 +759,10 @@ def cmp_status(bug_1, bug_2):
 
 def cmp_attr(bug_1, bug_2, attr, invert=False):
     """
-    Compare a general attribute between two bugs using the conventional
-    comparison rule for that attribute type.  If invert == True, sort
-    *against* that convention.
+    Compare a general attribute between two bugs using the
+    conventional comparison rule for that attribute type.  If
+    ``invert==True``, sort *against* that convention.
+
     >>> attr="severity"
     >>> bugA = Bug()
     >>> bugB = Bug()
diff --git a/libbe/bugdir.py b/libbe/bugdir.py
index 3c3afa0..fa8edb9 100644
--- a/libbe/bugdir.py
+++ b/libbe/bugdir.py
@@ -19,8 +19,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-"""
-Define the BugDir class for representing bug comments.
+"""Define the :class:`BugDir` class for storing a collection of bugs.
 """
 
 import copy
@@ -89,8 +88,10 @@ class DiskAccessRequired (Exception):
 
 
 class BugDir (list, settings_object.SavedSettingsObject):
-    """
-    TODO: simple bugdir manipulation examples...
+    """A BugDir is a container for :class:`libbe.bug.Bug`\s, with some
+    additional attributes.
+
+    See :class:`SimpleBugDir` for some bugdir manipulation exampes.
     """
 
     settings_properties = []
@@ -344,7 +345,8 @@ class RevisionedBugDir (BugDir):
 if libbe.TESTING == True:
     class SimpleBugDir (BugDir):
         """
-        For testing.  Set memory=True for a memory-only bugdir.
+        For testing.  Set ``memory=True`` for a memory-only bugdir.
+
         >>> bugdir = SimpleBugDir()
         >>> uuids = list(bugdir.uuids())
         >>> uuids.sort()
diff --git a/libbe/comment.py b/libbe/comment.py
index dd245de..003bf71 100644
--- a/libbe/comment.py
+++ b/libbe/comment.py
@@ -16,8 +16,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-"""
-Define the Comment class for representing bug comments.
+"""Define the :class:`Comment` class for representing bug comments.
 """
 
 import base64
@@ -101,7 +100,10 @@ def save_comments(bug):
 
 
 class Comment (Tree, settings_object.SavedSettingsObject):
-    """
+    """Comments are a notes that attach to :class:`libbe.bug.Bug`\s in
+    threaded trees.  In mailing-list terms, a comment is analogous to
+    a single part of an email.
+
     >>> c = Comment()
     >>> c.uuid != None
     True
@@ -194,19 +196,19 @@ class Comment (Tree, settings_object.SavedSettingsObject):
     def __init__(self, bug=None, uuid=None, from_storage=False,
                  in_reply_to=None, body=None, content_type=None):
         """
-        Set from_storage=True to load an old comment.
-        Set from_storage=False to create a new comment.
+        Set ``from_storage=True`` to load an old comment.
+        Set ``from_storage=False`` to create a new comment.
 
-        The uuid option is required when from_storage==True.
+        The ``uuid`` option is required when ``from_storage==True``.
 
         The in_reply_to, body, and content_type options are only used
-        if from_storage==False (the default).  When
-        from_storage==True, they are loaded from the bug database.
-        content_type decides if the body should be run through
-        libbe.util.id.short_to_long_text() before saving.  See
-        ._set_comment_body() for details.
+        if ``from_storage==False`` (the default).  When
+        ``from_storage==True``, they are loaded from the bug database.
+        ``content_type`` decides if the body should be run through
+        :func:`util.id.short_to_long_text` before saving.  See
+        :meth:`_set_comment_body` for details.
 
-        in_reply_to should be the uuid string of the parent comment.
+        ``in_reply_to`` should be the uuid string of the parent comment.
         """
         Tree.__init__(self)
         settings_object.SavedSettingsObject.__init__(self)
@@ -267,6 +269,7 @@ class Comment (Tree, settings_object.SavedSettingsObject):
     def safe_in_reply_to(self):
         """
         Return self.in_reply_to, except...
+
           * if no comment matches that id, in which case return None.
           * if that id matches another comments .alt_id, in which case
             return the matching comments .uuid.
@@ -337,7 +340,7 @@ class Comment (Tree, settings_object.SavedSettingsObject):
         return istring + sep.join(lines).rstrip('\n')
 
     def from_xml(self, xml_string, verbose=True):
-        """
+        u"""
         Note: If alt-id is not given, translates any <uuid> fields to
         <alt-id> fields.
         >>> commA = Comment(bug=None, body="Some\\ninsightful\\nremarks\\n")
@@ -412,6 +415,7 @@ class Comment (Tree, settings_object.SavedSettingsObject):
         """
         Merge info from other into this comment.  Overrides any
         attributes in self that are listed in other.explicit_attrs.
+
         >>> commA = Comment(bug=None, body='Some insightful remarks')
         >>> commA.uuid = '0123'
         >>> commA.date = 'Thu, 01 Jan 1970 00:00:00 +0000'
@@ -621,7 +625,7 @@ class Comment (Tree, settings_object.SavedSettingsObject):
         """
         Save any loaded contents to storage.
 
-        However, if self.storage.is_writeable() == True, then any
+        However, if ``self.storage.is_writeable() == True``, then any
         changes are automatically written to storage as soon as they
         happen, so calling this method will just waste time (unless
         something else has been messing with your stored files).
@@ -666,8 +670,8 @@ class Comment (Tree, settings_object.SavedSettingsObject):
         return reply
 
     def comment_from_uuid(self, uuid, match_alt_id=True):
-        """
-        Use a uuid to look up a comment.
+        """Use a uuid to look up a comment.
+
         >>> a = Comment(bug=None, uuid="a")
         >>> b = a.new_reply()
         >>> b.uuid = "b"
@@ -708,6 +712,7 @@ def cmp_attr(comment_1, comment_2, attr, invert=False):
     Compare a general attribute between two comments using the conventional
     comparison rule for that attribute type.  If invert == True, sort
     *against* that convention.
+
     >>> attr="author"
     >>> commentA = Comment()
     >>> commentB = Comment()