docstringing

Author: Michael Zingale

util/profile.py

@@ -36,10 +36,28 @@
 class TimerCollection:
 
     def __init__(self):
+        """
+        Initialize the collection of timers
+        """
         self.timers = []
 
 
     def timer(self, name):
+        """
+        Create a timer with the given name.  If one with that name already
+        exists, then we return that timer.
+
+        Parameters
+        ----------
+        name : str
+            Name of the timer
+
+        Returns
+        -------
+        out : Timer object
+            A timer object corresponding to the name.
+
+        """
 
         # check if any existing timer has this name, if so, return that
         # object
@@ -63,6 +81,9 @@ def timer(self, name):
 
 
     def report(self):
+        """
+        Generate a timing summary report
+        """
 
         spacing = '   '
         for t in self.timers:
@@ -72,7 +93,18 @@ def report(self):
 class Timer:
 
     def __init__ (self, name, stack_count=0):
-        
+        """
+        Initialize a timer with the given name.
+
+        Parameters
+        ----------
+        name : str
+            The name of the timer
+        stack_count : int, optional
+            The depth of the timer (i.e. how many timers is this nested
+            in).  This is used for printing purposes.
+
+        """
         self.name = name
         self.stack_count = stack_count
         self.is_running = False
@@ -82,11 +114,18 @@ def __init__ (self, name, stack_count=0):
 
 
     def begin(self):
+        """
+        Start timing
+        """
         self.start_time = time.time()
         self.is_running = True
 
 
     def end(self):
+        """
+        Stop timing.  This does not destroy the timer, it simply 
+        stops it from counting time.
+        """
         elapsed_time = time.time() - self.start_time
         self.elapsed_time += elapsed_time
         self.is_running = False

util/runparams.py

@@ -66,6 +66,11 @@ def is_float(string):
 class RuntimeParameters:
 
     def __init__ (self):
+        """
+        Initialize a collection of runtime parameters.  This class
+        holds a dictionary of the parameters, their comments, and keeps
+        track of which parameters were actually used.
+        """
 
         # keep track of the parameters and their comments 
         self.params = {}
@@ -77,8 +82,18 @@ def __init__ (self):
 
     def load_params(self, file, no_new=0):
         """
-        reads lines from file and makes dictionary pairs from the data
-        to store in self.params
+        Reads line from file and makes dictionary pairs from the data
+        to store.
+
+        Parameters
+        ----------
+        file : str
+            The name of the file to parse
+        no_new : int, optional
+            If no_new = 1, then we don't add any new paramters to the
+            dictionary of runtime parameters, but instead just override
+            the values of existing ones.
+
         """
 
         # check to see whether the file exists
@@ -142,6 +157,12 @@ def command_line_params(self, cmd_strings):
         we expect things in the string in the form:
          ["sec.opt=value",  "sec.opt=value"]
         with each opt an element in the list
+
+        Parameters
+        ----------
+        cmd_strings : list
+            The list of strings containing runtime parameter pairs            
+
         """
 
         for item in cmd_strings:
@@ -185,14 +206,17 @@ def get_param(self, key):
 
     def print_unused_params(self):
         """
-        print out the list of parameters that were defined by never used
+        Print out the list of parameters that were defined by never used
         """
         for key in self.params.keys():
             if not key in self.used_params:
                 msg.warning("parameter %s never used" % (key))
 
 
     def print_all_params(self):
+        """
+        Print out all runtime parameters and their values
+        """
         keys = self.params.keys()
         keys.sort()
 
@@ -203,6 +227,11 @@ def print_all_params(self):
 
 
     def print_paramfile(self):
+        """
+        Create a file, inputs.auto, that has the structure of a pyro
+        inputs file, with all known parameters and values
+        """
+
         keys = self.params.keys()
         keys.sort()