Improve comments in version.py

catch/utils/version.py

@@ -1,29 +1,53 @@
 #!/usr/bin/python
-''' This gets the git version into python-land
-'''
+"""This determines the catch package version, primarily based on git.
+
+If git is available, we use the version specified by git. This can indicate
+commits on top of the last numbered version and can also indicate if the
+working directory is dirty (i.e., has local modifications). If git is not
+available but some version from git was stored in a file, we use that. Finally,
+if none of these are available, we resort to the numbered version manually
+specified in the variable VERSION.
+"""
 
-__author__ = "dpark@broadinstitute.org"
-__version__ = None
 
 import subprocess
 import os
 import re
 import time, datetime
 
+__author__ = ['Danny Park <dpark@broadinstitute.org>',
+        'Hayden Metsky <hayden@mit.edu>']
+
+# Set __version__ lazily below
+__version__ = None
+
 
 def get_project_path():
-    '''Return the absolute path of the top-level project, assumed to be the
-       parent of the directory containing this script.'''
+    """Determine absolute path to the top-level of the catch project.
+
+    This is assumed to be the parent of the directory containing this script.
+
+    Returns:
+        path (string) to top-level of the catch project
+    """
     # abspath converts relative to absolute path; expanduser interprets ~
     path = __file__  # path to this script
     path = os.path.expanduser(path)  # interpret ~
     path = os.path.abspath(path)  # convert to absolute path
-    path = os.path.dirname(path)  # containing directory: util
-    path = os.path.dirname(path)  # containing directory: main project dir
+    path = os.path.dirname(path)  # containing directory: utils
+    path = os.path.dirname(path)  # containing directory: catch project dir
     return path
 
 
 def call_git_describe():
+    """Determine a version according to git.
+
+    This calls `git describe`, if git is available.
+
+    Returns:
+        version from `git describe --tags --always --dirty` if git is
+        available; otherwise, None
+    """
     cwd = os.getcwd()
     try:
         os.chdir(get_project_path())
@@ -39,10 +63,20 @@ def call_git_describe():
 
 
 def release_file():
+    """Obtain path to file storing version, according to git.
+
+    Returns:
+        path to VERSION file
+    """
     return os.path.join(get_project_path(), 'VERSION')
 
 
 def read_release_version():
+    """Read VERSION file, containing git version.
+
+    Returns:
+        if VERSION file exists, version stored in it; otherwise, None
+    """
     try:
         with open(release_file(), 'rt') as inf:
             version = inf.readlines()[0].strip()
@@ -52,6 +86,11 @@ def read_release_version():
 
 
 def write_release_version(version):
+    """Save version, according to git, into VERSION file.
+
+    Args:
+        version: version to save
+    """
     with open(release_file(), 'wt') as outf:
         outf.write(version + '\n')
 
@@ -94,7 +133,10 @@ def approx_version_number():
 
     return version
 
+
 def get_version():
+    """Determine version from git, and save if available.
+    """
     global __version__
     if __version__ is None:
         from_git = call_git_describe()
@@ -114,4 +156,5 @@ def get_version():
 
 
 if __name__ == "__main__":
+    # Determine and print the package version
     print(get_version())