diff --git a/tools/subunit_to_junit.py b/tools/subunit_to_junit.py
index 572daea7a681..2dffe303f9b2 100755
--- a/tools/subunit_to_junit.py
+++ b/tools/subunit_to_junit.py
@@ -16,10 +16,12 @@
 # package, https://github.com/testing-cabal/subunit/ just adapted to run on
 # python3 more reliably.
 
+"""Script to convert subunit stream returned by stestr to junitxml for processing by azure-pipelines."""
+
 import argparse
 import sys
 
-from junitxml import JUnitXmlResult
+from junitxml import JUnitXmlResult  # pylint: disable=import-error
 from subunit.filters import run_tests_from_stream
 from testtools import StreamToExtendedDecorator
 
@@ -35,20 +37,22 @@ def filter_by_result(
 ):
     """Filter an input stream using a test result.
 
-    :param result_factory: A callable that when passed an output stream
+    :param callable result_factory: A callable that when passed an output stream
         returns a TestResult.  It is expected that this result will output
         to the given stream.
-    :param output_path: A path send output to.  If None, output will be go
+    :param str output_path: A path send output to.  If None, output will be go
         to ``sys.stdout``.
-    :param passthrough: If True, all non-subunit input will be sent to
+    :param bool passthrough: If True, all non-subunit input will be sent to
         ``sys.stdout``.  If False, that input will be discarded.
-    :param forward: If True, all subunit input will be forwarded directly to
+    :param bool forward: If True, all subunit input will be forwarded directly to
         ``sys.stdout`` as well as to the ``TestResult``.
-    :param input_stream: The source of subunit input.  Defaults to
+    :param file input_stream: The source of subunit input.  Defaults to
         ``sys.stdin``.
-    :param protocol_version: The subunit protocol version to expect.
-    :param passthrough_subunit: If True, passthrough should be as subunit.
+    :param int protocol_version: The subunit protocol version to expect.
+    :param bool passthrough_subunit: If True, passthrough should be as subunit.
+
     :return: A test result with the results of the run.
+    :rtype: JUnitXmlResult
     """
     if protocol_version == 1:
         sys.stderr.write("Subunit protocol version 2 must be used")
@@ -95,11 +99,14 @@ def run_filter_script(
     wraps a lot of the boiler-plate around that by making a script with
     options for handling passthrough information and stream forwarding
 
-    :param result_factory: A callable that takes an output stream and returns
+    :param callable 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.
-    :param protocol_version: What protocol version to consume/emit.
-    :param passthrough_subunit: If True, passthrough should be as subunit.
+    :param str description: A description of the filter script.
+    :param callable post_run_hook: A callback function that runs after the test run
+        finishes. It will be passed a single positional argument the result
+        object returned by the run.
+    :param int protocol_version: What protocol version to consume/emit.
+    :param bool passthrough_subunit: If True, passthrough should be as subunit.
     """
     parser = argparse.ArgumentParser(description=description)
     parser.add_argument(
@@ -135,7 +142,7 @@ def run_filter_script(
         result = result.decorated
 
 
-def main():
+def _main():
     run_filter_script(
         lambda output: StreamToExtendedDecorator(JUnitXmlResult(output)),
         "Convert to junitxml",
@@ -144,4 +151,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    _main()