Remove non-conformant comments and add docstrings to series.py.

1 files changed, 58 insertions, 10 deletions

diff --git a/linaropy/series.py b/linaropy/series.py
index 3db2c97..3e6830c 100644
--- a/linaropy/series.py
+++ b/linaropy/series.py
@@ -13,9 +13,11 @@ from datetime import datetime
 from dateutil.relativedelta import relativedelta
 
 
-# A Series stores the instance characteristic that describes the output
 class Series(object):
-
+    """
+    A Series represents a package candidate, snapshot, or release and includes
+    version, package, date, and spin information.
+    """
     series = ['candidate', 'snapshot', 'release']
     serieslongupper = ['Release-Candidate', 'Snapshot', 'Release']
 
@@ -31,6 +33,35 @@ class Series(object):
     # This will make sure snapshot doesn't have an rc and release doesn't have
     # an rc for instance.
     def __init__(self, seriestype, vendor=None, package=None, date=datetime.today(), spin=None, rc=None, strict=True):
+	"""
+	Create a Series to store the details on a package release, snapshot,
+	or release-candidate.
+
+	Parameters
+	----------
+	seriestype : str
+            "candidate", "release", or "snapshot"
+
+	vendor : str
+	    A String representing the vendor for the series.  The default is
+	    inherited from the Vendor class.
+
+	package : str or Package
+	    Designate the package that this Series represents, for example,
+	    'gcc'.  The default is inherited from the Package class.
+
+	date : str or datetime
+	    "YYYY.MM", "YY.MM", or a datetime object representing the Series.
+
+	spin : Spin
+	    A spin number for the Series.
+
+	rc : Rc
+	    An rc number for the Series.
+
+	strict=True : bool
+	    Enforce rules regarding whether candidates can/cannot have Rcs.
+	"""
         if isinstance(spin, Spin):
     	    self.spin=spin
         else:
@@ -143,11 +174,9 @@ class Series(object):
 	ret=''
 	# Iterate across the dictionary and for each key found and invoke the
 	# function.
-	# self.fmt[idx]()
 	import string
 	ret=format_spec
 	for key in self.fmt.iterkeys():
-            # TOOD: Crap this isn't going to work because each function takes different parameters.
 	    replac=self.fmt[key]()
 	    ret=string.replace(ret,key,replac)
 	return ret
@@ -180,9 +209,6 @@ class Series(object):
     def incrementMonth(self):
 	self.date = self.date + relativedelta(months=1)
 
-    # TODO: provide a format function which can change the separator and
-    # capitalization, etc.
-
     def getDir(self):
 	dirstr=self.package.version.strfversion("%M%m")
 	dirstr=dirstr + u'-' + self.date.strftime("%Y.%m")
@@ -213,9 +239,31 @@ class Series(object):
 
 	return branchname
 
-# Helper function which creates a Series from a properly formed branch name
-# input string.
 def seriesFromBranchname(branch=None):
+    """
+    Create a Series from a branch name string.
+
+    Parameters
+    ----------
+    branch : str
+
+        The branchname of a package as it lives in a git repository.  A properly formed
+	branch name has the following elements, where options in brackets are optional:
+
+	<namespace>/<package-version>-<YYYY>.<MM>[-spin][-rcN]
+
+	Snapshot
+	--------
+	snapshots/<foo>[!-rcN]
+
+	Candidate
+	---------
+	releases/<foo>-rcN
+
+	Release
+	-------
+	releases/<foo>[!-rcN]
+    """
     if not isinstance(branch, basestring):
 	raise TypeError('seriesFromBranchname requires a basestring as input')
 
@@ -297,7 +345,7 @@ def seriesFromBranchname(branch=None):
 from vers import versionFromStr
 
 class TestSeries(unittest.TestCase):
-
+    """Test the Series class using the unittest framework."""
     def test_missing_seriestype(self):
 	with self.assertRaises(TypeError):
 	    spin=Spin()