Rename main() and give it a docstring.

3 files changed, 19 insertions, 7 deletions

diff --git a/filters/subunit2csv b/filters/subunit2csv
index 0357b1d..14620ff 100755
--- a/filters/subunit2csv
+++ b/filters/subunit2csv
@@ -8,7 +8,7 @@
 #  compliance with one of these two licences.
 #
 #  Unless required by applicable law or agreed to in writing, software
-#  distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
+#  distributed under these licenses is d on an "AS IS" BASIS, WITHOUT
 #  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
 #  license you chose for the specific language governing permissions and
 #  limitations under that license.
@@ -16,8 +16,8 @@
 
 """Turn a subunit stream into a CSV"""
 
-from subunit.filters import main
+from subunit.filters import run_filter_script
 from subunit.test_results import CsvResult
 
 
-main(CsvResult, __doc__)
+run_filter_script(CsvResult, __doc__)
diff --git a/filters/subunit2junitxml b/filters/subunit2junitxml
index 18d170e..d568c71 100755
--- a/filters/subunit2junitxml
+++ b/filters/subunit2junitxml
@@ -18,7 +18,7 @@
 
 
 import sys
-from subunit.filters import main
+from subunit.filters import run_filter_script
 
 try:
     from junitxml import JUnitXmlResult
@@ -28,4 +28,4 @@ except ImportError:
     raise
 
 
-main(JUnitXmlResult, __doc__)
+run_filter_script(JUnitXmlResult, __doc__)
diff --git a/python/subunit/filters.py b/python/subunit/filters.py
index 0bab9ed..f8ce2dd 100644
--- a/python/subunit/filters.py
+++ b/python/subunit/filters.py
@@ -18,7 +18,6 @@ from optparse import OptionParser
 import sys
 
 from subunit import DiscardStream, ProtocolTestCase
-from subunit.test_results import CsvResult
 
 
 def make_options(description):
@@ -106,7 +105,20 @@ def filter_by_result(result_factory, output_path, no_passthrough, forward,
         return 1
 
 
-def main(result_factory, description):
+def run_filter_script(result_factory, description):
+    """Main function for simple subunit filter scripts.
+
+    Many subunit filter scripts take a stream of subunit input and use a
+    TestResult to handle the events generated by that stream.  This function
+    wraps a lot of the boiler-plate around that by making a script with
+    options for handling passthrough information and stream forwarding, and
+    that will exit with a successful return code (i.e. 0) if the input stream
+    represents a successful test run.
+
+    :param result_factory: A callable that takes an output stream and returns
+        a test result that outputs to that stream.
+    :param description: A description of the filter script.
+    """
     parser = make_options(description)
     (options, args) = parser.parse_args()
     sys.exit(