Begun documenting pymagglobal.commands

pymagglobal/commands.py

@@ -40,25 +40,28 @@ from . import utils
 
 
 class OutOfRangeWarning(Warning):
-    ''' just to give the warning a meaningful name '''
+    '''Just to give the warning a meaningful name.'''
     pass
 
 
 def valid_epoch(args):
-    ''' check whether the epoch given via the command line is in the range of
-    the model
+    '''Check whether the epoch given via the command line is in the range of
+    the model.
 
     Parameters
     ----------
     args : object
-        the object returned by ArgumentParser.parse_args()
+        An object that provides access to attributes `input`, `longerm` and
+        `epoch` e.g. the SimpleNamspace object returned by
+        ArgumentParser.parse_args().
 
     Returns
     -------
     float
-        the epoch in yrs
+        The epoch in years.
     '''
     # get the range of the model from the model file
+    # XXX Duplication of code see file2splines()
     with open(args.input, 'r') as fh:
         t_min, t_max = map(float, fh.readline().split()[0:2])
     if args.longterm:
@@ -73,14 +76,20 @@ def valid_epoch(args):
 
 
 def args2times(args):
-    ''' read the range of the model and create a linear array to evaluate it.
-    make use of the command line arguments --every and --res
+    '''Read the range of the model and create a linear array to evaluate it.
+    Make use of the command line arguments `--every` and `--res`.
 
     Parameters
     ----------
     args : object
-        the object returned by ArgumentParser.parse_args()
+        The SimpleNamespace object returned by ArgumentParser.parse_args().
+
+    Returns
+    -------
+    times : ndarray
+        An equally spaced array in years.
     '''
+    # XXX Duplication of code see file2splines()
     with open(args.input, 'r') as fh:
         t_min, t_max = map(float, fh.readline().split()[0:2])
     if args.begin is not None:
@@ -104,8 +113,20 @@ def args2times(args):
 
 
 def yr2lt(times):
-    ''' translate times given as years to the format / age often used
-    for longterm models '''
+    '''Translate times given in years AD into kilo-years `before present
+    <https://en.wikipedia.org/wiki/Before_Present>`_ often used for
+    longterm models.
+
+    Parameters
+    ----------
+    times: float or int
+        Years AD.
+
+    Returns
+    -------
+    float
+       Kilo years before present (backward counting from 1/1/1950).
+    '''
     return -(times - 1950) / 1000