Added docstrings to libbe submodules.

Also a few minor tweaks to the module imports.

21 files changed, 126 insertions, 32 deletions

diff --git a/.be/bugs/764b812f-a0bb-4f4d-8e2f-c255c9474a0e/values b/.be/bugs/764b812f-a0bb-4f4d-8e2f-c255c9474a0e/values
index 631d1d6..4406356 100644
--- a/.be/bugs/764b812f-a0bb-4f4d-8e2f-c255c9474a0e/values
+++ b/.be/bugs/764b812f-a0bb-4f4d-8e2f-c255c9474a0e/values
@@ -7,7 +7,7 @@ reporter: W. Trevor King <wking@drexel.edu>
 severity: minor
 
 
-status: open
+status: fixed
 
 
 summary: Add docstrings explaining role of the libbe submodules.
diff --git a/Makefile b/Makefile
index fe482c3..61f67c8 100644
--- a/Makefile
+++ b/Makefile
@@ -38,8 +38,8 @@ MODULES += ${DOC_DIR}
 
 RM = rm
 
-#PREFIX = /usr/local
-PREFIX = ${HOME}
+PREFIX = /usr/local
+#PREFIX = ${HOME}
 INSTALL_OPTIONS = "--prefix=${PREFIX}"
 
 
diff --git a/libbe/arch.py b/libbe/arch.py
index b68d732..ab55172 100644
--- a/libbe/arch.py
+++ b/libbe/arch.py
@@ -17,6 +17,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+"""
+GNU Arch (tla) backend.
+"""
+
 import codecs
 import os
 import re
@@ -26,10 +30,11 @@ import time
 import unittest
 import doctest
 
-import config
 from beuuid import uuid_gen
+import config
 import vcs
-from vcs import VCS
+
+
 
 DEFAULT_CLIENT = "tla"
 
@@ -38,7 +43,7 @@ client = config.get_val("arch_client", default=DEFAULT_CLIENT)
 def new():
     return Arch()
 
-class Arch(VCS):
+class Arch(vcs.VCS):
     name = "Arch"
     client = client
     versioned = True
@@ -246,7 +251,7 @@ class Arch(VCS):
         pass
     def _vcs_get_file_contents(self, path, revision=None, binary=False):
         if revision == None:
-            return VCS._vcs_get_file_contents(self, path, revision, binary=binary)
+            return vcs.VCS._vcs_get_file_contents(self, path, revision, binary=binary)
         else:
             status,output,error = \
                 self._invoke_client("file-find", path, revision)
@@ -258,7 +263,7 @@ class Arch(VCS):
             return contents
     def _vcs_duplicate_repo(self, directory, revision=None):
         if revision == None:
-            VCS._vcs_duplicate_repo(self, directory, revision)
+            vcs.VCS._vcs_duplicate_repo(self, directory, revision)
         else:
             status,output,error = \
                 self._u_invoke_client("get", revision,directory)
diff --git a/libbe/beuuid.py b/libbe/beuuid.py
index bc47208..490ed62 100644
--- a/libbe/beuuid.py
+++ b/libbe/beuuid.py
@@ -13,6 +13,7 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
 """
 Backwards compatibility support for Python 2.4.  Once people give up
 on 2.4 ;), the uuid call should be merged into bugdir.py
@@ -20,6 +21,7 @@ on 2.4 ;), the uuid call should be merged into bugdir.py
 
 import unittest
 
+
 try:
     from uuid import uuid4 # Python >= 2.5
     def uuid_gen():
diff --git a/libbe/bug.py b/libbe/bug.py
index 6551fcf..fd30ff7 100644
--- a/libbe/bug.py
+++ b/libbe/bug.py
@@ -15,6 +15,11 @@
 # You should have received a copy of the GNU General Public License along
 # 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.
+"""
+
 import os
 import os.path
 import errno
diff --git a/libbe/bugdir.py b/libbe/bugdir.py
index af43917..c4f0f91 100644
--- a/libbe/bugdir.py
+++ b/libbe/bugdir.py
@@ -17,6 +17,11 @@
 # You should have received a copy of the GNU General Public License along
 # 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.
+"""
+
 import copy
 import errno
 import os
@@ -38,6 +43,7 @@ import settings_object
 import upgrade
 import utility
 
+
 class NoBugDir(Exception):
     def __init__(self, path):
         msg = "The directory \"%s\" has no bug directory." % path
diff --git a/libbe/bzr.py b/libbe/bzr.py
index 48bfd64..c551ff0 100644
--- a/libbe/bzr.py
+++ b/libbe/bzr.py
@@ -17,6 +17,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+"""
+Bazaar (bzr) backend.
+"""
+
 import os
 import re
 import sys
@@ -24,12 +28,12 @@ import unittest
 import doctest
 
 import vcs
-from vcs import VCS
+
 
 def new():
     return Bzr()
 
-class Bzr(VCS):
+class Bzr(vcs.VCS):
     name = "bzr"
     client = "bzr"
     versioned = True
@@ -60,14 +64,14 @@ class Bzr(VCS):
         pass
     def _vcs_get_file_contents(self, path, revision=None, binary=False):
         if revision == None:
-            return VCS._vcs_get_file_contents(self, path, revision, binary=binary)
+            return vcs.VCS._vcs_get_file_contents(self, path, revision, binary=binary)
         else:
             status,output,error = \
                 self._u_invoke_client("cat","-r",revision,path)
             return output
     def _vcs_duplicate_repo(self, directory, revision=None):
         if revision == None:
-            VCS._vcs_duplicate_repo(self, directory, revision)
+            vcs.VCS._vcs_duplicate_repo(self, directory, revision)
         else:
             self._u_invoke_client("branch", "--revision", revision,
                                   ".", directory)
diff --git a/libbe/cmdutil.py b/libbe/cmdutil.py
index 94a6856..8c1c612 100644
--- a/libbe/cmdutil.py
+++ b/libbe/cmdutil.py
@@ -15,6 +15,11 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""
+Define assorted utilities to make command-line handling easier.
+"""
+
 import glob
 import optparse
 import os
diff --git a/libbe/comment.py b/libbe/comment.py
index 5cb1129..19c556f 100644
--- a/libbe/comment.py
+++ b/libbe/comment.py
@@ -16,6 +16,11 @@
 # You should have received a copy of the GNU General Public License along
 # 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.
+"""
+
 import base64
 import os
 import os.path
diff --git a/libbe/config.py b/libbe/config.py
index 5e343b9..fb5a028 100644
--- a/libbe/config.py
+++ b/libbe/config.py
@@ -14,6 +14,11 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""
+Create, save, and load the per-user config file at path().
+"""
+
 import ConfigParser
 import codecs
 import locale
@@ -21,6 +26,7 @@ import os.path
 import sys
 import doctest
 
+
 default_encoding = sys.getfilesystemencoding() or locale.getpreferredencoding()
 
 def path():
diff --git a/libbe/darcs.py b/libbe/darcs.py
index 3bbbed9..16005f2 100644
--- a/libbe/darcs.py
+++ b/libbe/darcs.py
@@ -14,6 +14,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+"""
+Darcs backend.
+"""
+
 import codecs
 import os
 import re
@@ -27,12 +31,12 @@ import doctest
 import unittest
 
 import vcs
-from vcs import VCS
+
 
 def new():
     return Darcs()
 
-class Darcs(VCS):
+class Darcs(vcs.VCS):
     name="darcs"
     client="darcs"
     versioned=True
@@ -90,7 +94,7 @@ class Darcs(VCS):
         pass # darcs notices changes
     def _vcs_get_file_contents(self, path, revision=None, binary=False):
         if revision == None:
-            return VCS._vcs_get_file_contents(self, path, revision,
+            return vcs.VCS._vcs_get_file_contents(self, path, revision,
                                               binary=binary)
         else:
             try:
@@ -118,7 +122,7 @@ class Darcs(VCS):
                 status,output,error = self._u_invoke(args, stdin=target_patch)
 
                 if os.path.exists(os.path.join(self.rootdir, path)) == True:
-                    contents = VCS._vcs_get_file_contents(self, path,
+                    contents = vcs.VCS._vcs_get_file_contents(self, path,
                                                           binary=binary)
                 else:
                     contents = ""
@@ -128,12 +132,12 @@ class Darcs(VCS):
                 status,output,error = self._u_invoke(args, stdin=target_patch)
                 args=["patch", path]
                 status,output,error = self._u_invoke(args, stdin=major_patch)
-                current_contents = VCS._vcs_get_file_contents(self, path,
+                current_contents = vcs.VCS._vcs_get_file_contents(self, path,
                                                               binary=binary)
                 return contents
     def _vcs_duplicate_repo(self, directory, revision=None):
         if revision==None:
-            VCS._vcs_duplicate_repo(self, directory, revision)
+            vcs.VCS._vcs_duplicate_repo(self, directory, revision)
         else:
             self._u_invoke_client("put", "--to-patch", revision, directory)
     def _vcs_commit(self, commitfile, allow_empty=False):
diff --git a/libbe/diff.py b/libbe/diff.py
index 6c5828d..9253a23 100644
--- a/libbe/diff.py
+++ b/libbe/diff.py
@@ -14,12 +14,16 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-"""Compare two bug trees"""
-from libbe import bugdir, bug, settings_object, tree
-from libbe.utility import time_to_str
+
+"""Compare two bug trees."""
+
 import difflib
 import doctest
 
+from libbe import bugdir, bug, settings_object, tree
+from libbe.utility import time_to_str
+
+
 class DiffTree (tree.Tree):
     """
     A tree holding difference data for easy report generation.
diff --git a/libbe/editor.py b/libbe/editor.py
index 8f2bdbf..ec41006 100644
--- a/libbe/editor.py
+++ b/libbe/editor.py
@@ -15,6 +15,11 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+"""
+Define editor_string(), a function that invokes an editor to accept
+user-produced text as a string.
+"""
+
 import codecs
 import locale
 import os
@@ -22,6 +27,7 @@ import sys
 import tempfile
 import doctest
 
+
 default_encoding = sys.getfilesystemencoding() or locale.getpreferredencoding()
 
 comment_marker = u"== Anything below this line will be ignored\n"
diff --git a/libbe/encoding.py b/libbe/encoding.py
index 4af864e..fd513b5 100644
--- a/libbe/encoding.py
+++ b/libbe/encoding.py
@@ -14,11 +14,17 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""
+Support input/output/filesystem encodings (e.g. UTF-8).
+"""
+
 import codecs
 import locale
 import sys
 import doctest
 
+
 ENCODING = None # override get_encoding() output by setting this
 
 def get_encoding():
diff --git a/libbe/git.py b/libbe/git.py
index 3345b57..137cb35 100644
--- a/libbe/git.py
+++ b/libbe/git.py
@@ -16,6 +16,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+"""
+Git backend.
+"""
+
 import os
 import re
 import sys
@@ -23,12 +27,12 @@ import unittest
 import doctest
 
 import vcs
-from vcs import VCS
+
 
 def new():
     return Git()
 
-class Git(VCS):
+class Git(vcs.VCS):
     name="git"
     client="git"
     versioned=True
@@ -89,14 +93,14 @@ class Git(VCS):
         self._vcs_add(path)
     def _vcs_get_file_contents(self, path, revision=None, binary=False):
         if revision == None:
-            return VCS._vcs_get_file_contents(self, path, revision, binary=binary)
+            return vcs.VCS._vcs_get_file_contents(self, path, revision, binary=binary)
         else:
             arg = "%s:%s" % (revision,path)
             status,output,error = self._u_invoke_client("show", arg)
             return output
     def _vcs_duplicate_repo(self, directory, revision=None):
         if revision==None:
-            VCS._vcs_duplicate_repo(self, directory, revision)
+            vcs.VCS._vcs_duplicate_repo(self, directory, revision)
         else:
             #self._u_invoke_client("archive", revision, directory) # makes tarball
             self._u_invoke_client("clone", "--no-checkout",".",directory)
diff --git a/libbe/hg.py b/libbe/hg.py
index c7c736e..f8f8121 100644
--- a/libbe/hg.py
+++ b/libbe/hg.py
@@ -16,6 +16,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+"""
+Mercurial (hg) backend.
+"""
+
 import os
 import re
 import sys
@@ -23,12 +27,12 @@ import unittest
 import doctest
 
 import vcs
-from vcs import VCS
+
 
 def new():
     return Hg()
 
-class Hg(VCS):
+class Hg(vcs.VCS):
     name="hg"
     client="hg"
     versioned=True
@@ -63,14 +67,14 @@ class Hg(VCS):
         pass
     def _vcs_get_file_contents(self, path, revision=None, binary=False):
         if revision == None:
-            return VCS._vcs_get_file_contents(self, path, revision, binary=binary)
+            return vcs.VCS._vcs_get_file_contents(self, path, revision, binary=binary)
         else:
             status,output,error = \
                 self._u_invoke_client("cat","-r",revision,path)
             return output
     def _vcs_duplicate_repo(self, directory, revision=None):
         if revision == None:
-            return VCS._vcs_duplicate_repo(self, directory, revision)
+            return vcs.VCS._vcs_duplicate_repo(self, directory, revision)
         else:
             self._u_invoke_client("archive", "--rev", revision, directory)
     def _vcs_commit(self, commitfile, allow_empty=False):
diff --git a/libbe/mapfile.py b/libbe/mapfile.py
index 60def4d..4d69601 100644
--- a/libbe/mapfile.py
+++ b/libbe/mapfile.py
@@ -14,12 +14,19 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-import yaml
-import os.path
+
+"""
+Provide a means of saving and loading dictionaries of parameters.  The
+saved "mapfiles" should be clear, flat-text files, and allow easy merging of
+independent/conflicting changes.
+"""
+
 import errno
-import utility
+import os.path
+import yaml
 import doctest
 
+
 class IllegalKey(Exception):
     def __init__(self, key):
         Exception.__init__(self, 'Illegal key "%s"' % key)
diff --git a/libbe/plugin.py b/libbe/plugin.py
index 0545fd7..d593d69 100644
--- a/libbe/plugin.py
+++ b/libbe/plugin.py
@@ -15,6 +15,12 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""
+Allow simple listing and loading of the various becommands and libbe
+submodules (i.e. "plugins").
+"""
+
 import os
 import os.path
 import sys
diff --git a/libbe/tree.py b/libbe/tree.py
index 45ae085..06d09e5 100644
--- a/libbe/tree.py
+++ b/libbe/tree.py
@@ -15,6 +15,10 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+"""
+Define a traversable tree structure.
+"""
+
 import doctest
 
 class Tree(list):
diff --git a/libbe/utility.py b/libbe/utility.py
index 3df06b4..aafbf8d 100644
--- a/libbe/utility.py
+++ b/libbe/utility.py
@@ -14,6 +14,11 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""
+Assorted utility functions that don't fit in anywhere else.
+"""
+
 import calendar
 import codecs
 import os
diff --git a/libbe/vcs.py b/libbe/vcs.py
index e2916e6..3ee1a44 100644
--- a/libbe/vcs.py
+++ b/libbe/vcs.py
@@ -18,6 +18,12 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+"""
+Define the base VCS (Version Control System) class, which should be
+subclassed by other Version Control System backends.  The base class
+implements a "do not version" VCS.
+"""
+
 from subprocess import Popen, PIPE
 import codecs
 import os