Update docstrings for more clarity

Add some clarity about inputs and outputs to steps, and on
where super().run() needs to get called in a test case's overridden
version of this method.

Add docstrings for run_step() and run_test_case()

compass/step.py

@@ -17,6 +17,10 @@ class Step:
     own by a user, though users will typically run full test cases or test
     suites.
 
+    Below, the terms "input" and "output" refer to inputs and outputs to the
+    step itself, not necessarily the MPAS model.  In fact, the MPAS model
+    itself is often an input to the step.
+
     Attributes
     ----------
     name : str
@@ -200,10 +204,10 @@ def run(self):
     def add_input_file(self, filename=None, target=None, database=None,
                        url=None, work_dir_target=None):
         """
-        Add an input file to the step.  The file can be local, a symlink to
-        a file that will be created in another step, a symlink to a file in one
-        of the databases for files cached after download, and/or come from a
-        specified URL.
+        Add an input file to the step (but not necessarily to the MPAS model).
+        The file can be local, a symlink to a file that will be created in
+        another step, a symlink to a file in one of the databases for files
+        cached after download, and/or come from a specified URL.
 
         Parameters
         ----------
@@ -252,7 +256,9 @@ def add_input_file(self, filename=None, target=None, database=None,
 
     def add_output_file(self, filename):
         """
-        Add the output file to the step
+        Add the output file that must be produced by this step and may be made
+        available as an input to steps, perhaps in other test cases.  This file
+        must exist after the test has run or an exception will be raised.
 
         Parameters
         ----------
@@ -530,6 +536,10 @@ def _generate_streams(self):
 
 
 def run_step():
+    """
+    Used by the framework to run a step when ``compass run`` gets called in the
+    step's work directory
+    """
     with open('step.pickle', 'rb') as handle:
         test_case, step = pickle.load(handle)
     test_case.steps_to_run = [step.name]

compass/testcase.py

@@ -122,6 +122,11 @@ def run(self):
         to perform additional operations in addition to running the test case's
         steps
 
+        Developers need to make sure they call ``super().run()`` at some point
+        in the overridden ``run()`` method to actually call the steps of the
+        run.  The developer will need to decide where in the overridden method
+        to make the call to ``super().run()``, after any updates to steps
+        based on config options but before validation.
         """
         logger = self.logger
         cwd = os.getcwd()
@@ -232,6 +237,10 @@ def _run_step(self, step, new_log_file):
 
 
 def run_test_case():
+    """
+    Used by the framework to run a test case when ``compass run`` gets called
+    in the test case's work directory
+    """
     with open('test_case.pickle', 'rb') as handle:
         test_case = pickle.load(handle)