Fix Python docstrings to match style guide

https://google.github.io/styleguide/pyguide.html#s3.8.3-functions-and-methods

PiperOrigin-RevId: 504857416
Change-Id: I7815ce27e454a120b3974ae7e2bea952108b836c

7 files changed, 88 insertions, 33 deletions

diff --git a/googletest/test/googletest-break-on-failure-unittest.py b/googletest/test/googletest-break-on-failure-unittest.py
index 3f65812..e314b5c 100755
--- a/googletest/test/googletest-break-on-failure-unittest.py
+++ b/googletest/test/googletest-break-on-failure-unittest.py
@@ -88,13 +88,17 @@ def Run(command):
 
 
 class GTestBreakOnFailureUnitTest(gtest_test_utils.TestCase):
-  """Tests using the GTEST_BREAK_ON_FAILURE environment variable or
+  """Unit test for Google Test's break-on-failure mode.
+
+  Tests using the GTEST_BREAK_ON_FAILURE environment variable or
   the --gtest_break_on_failure flag to turn assertion failures into
   segmentation faults.
   """
 
   def RunAndVerify(self, env_var_value, flag_value, expect_seg_fault):
-    """Runs googletest-break-on-failure-unittest_ and verifies that it does
+    """Runs googletest-break-on-failure-unittest_ and verifies its behavior.
+
+    Runs googletest-break-on-failure-unittest_ and verifies that it does
     (or does not) have a seg-fault.
 
     Args:
diff --git a/googletest/test/googletest-list-tests-unittest.py b/googletest/test/googletest-list-tests-unittest.py
index f59fca0..977e57f 100755
--- a/googletest/test/googletest-list-tests-unittest.py
+++ b/googletest/test/googletest-list-tests-unittest.py
@@ -132,7 +132,9 @@ class GTestListTestsUnitTest(gtest_test_utils.TestCase):
   """Tests using the --gtest_list_tests flag to list all tests."""
 
   def RunAndVerify(self, flag_value, expected_output_re, other_flag):
-    """Runs googletest-list-tests-unittest_ and verifies that it prints
+    """Run googletest-list-tests-unittest_ and verify the output.
+
+    Runs googletest-list-tests-unittest_ and verifies that it prints
     the correct tests.
 
     Args:
@@ -206,7 +208,9 @@ class GTestListTestsUnitTest(gtest_test_utils.TestCase):
     )
 
   def testWithFilterFlags(self):
-    """Tests that --gtest_list_tests takes into account the
+    """Tests that --gtest_list_tests takes into account the filter flags.
+
+    Tests that --gtest_list_tests takes into account the
     --gtest_filter flag.
     """
 
diff --git a/googletest/test/googletest-output-test.py b/googletest/test/googletest-output-test.py
index 5185ed9..347b854 100755
--- a/googletest/test/googletest-output-test.py
+++ b/googletest/test/googletest-output-test.py
@@ -237,13 +237,16 @@ def GetShellCommandOutput(env_cmd):
 
 
 def GetCommandOutput(env_cmd):
-  """Runs a command and returns its output with all file location
-  info stripped off.
+  """Runs a command and returns output with all file location info stripped off.
 
   Args:
     env_cmd:  The shell command. A 2-tuple where element 0 is a dict of extra
       environment variables to set, and element 1 is a string with the command
       and any flags.
+
+  Returns:
+    A string with the command's combined standard and diagnostic output. File
+    location info is stripped.
   """
 
   # Disables exception pop-ups on Windows.
diff --git a/googletest/test/googletest-throw-on-failure-test.py b/googletest/test/googletest-throw-on-failure-test.py
index 282163b..106b004 100755
--- a/googletest/test/googletest-throw-on-failure-test.py
+++ b/googletest/test/googletest-throw-on-failure-test.py
@@ -55,8 +55,14 @@ EXE_PATH = gtest_test_utils.GetTestExecutablePath(
 
 
 def SetEnvVar(env_var, value):
-  """Sets an environment variable to a given value; unsets it when the
+  """Sets an environment variable.
+
+  Sets an environment variable to a given value; unsets it when the
   given value is None.
+
+  Args:
+    env_var: environment variable.
+    value: value to set.
   """
 
   env_var = env_var.upper()
@@ -79,7 +85,9 @@ class ThrowOnFailureTest(gtest_test_utils.TestCase):
   """Tests the throw-on-failure mode."""
 
   def RunAndVerify(self, env_var_value, flag_value, should_fail):
-    """Runs googletest-throw-on-failure-test_ and verifies that it does
+    """Runs googletest-throw-on-failure-test_ and verifies its behavior.
+
+    Runs googletest-throw-on-failure-test_ and verifies that it does
     (or does not) exit with a non-zero code.
 
     Args:
diff --git a/googletest/test/gtest_help_test.py b/googletest/test/gtest_help_test.py
index 1d67415..fda40bf 100755
--- a/googletest/test/gtest_help_test.py
+++ b/googletest/test/gtest_help_test.py
@@ -187,14 +187,18 @@ class GTestHelpTest(gtest_test_utils.TestCase):
       self.TestHelpFlag(UNKNOWN_GTEST_PREFIXED_FLAG)
 
   def testRunsTestsWithoutHelpFlag(self):
-    """Verifies that when no help flag is specified, the tests are run
+    """Verifies correct behavior when no help flag is specified.
+
+    Verifies that when no help flag is specified, the tests are run
     and the help message is not printed.
     """
 
     self.TestNonHelpFlag(None)
 
   def testRunsTestsWithGtestInternalFlag(self):
-    """Verifies that the tests are run and no help message is printed when
+    """Verifies correct behavior when internal testing flag is specified.
+
+    Verifies that the tests are run and no help message is printed when
     a flag starting with Google Test prefix and 'internal_' is supplied.
     """
 
diff --git a/googletest/test/gtest_xml_output_unittest.py b/googletest/test/gtest_xml_output_unittest.py
index d48d1af..e46ad39 100755
--- a/googletest/test/gtest_xml_output_unittest.py
+++ b/googletest/test/gtest_xml_output_unittest.py
@@ -246,7 +246,8 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase):
   # type-parameterized tests, so we don't run it under them.
   if SUPPORTS_TYPED_TESTS:
     def testNonEmptyXmlOutput(self):
-      """
+      """Generates non-empty XML and verifies it matches the expected output.
+
       Runs a test program that generates a non-empty XML output, and
       tests that the XML output is expected.
       """
@@ -286,7 +287,8 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase):
     actual.unlink()
 
   def testDefaultOutputFile(self):
-    """
+    """Tests XML file with default name is created when name is not specified.
+
     Confirms that Google Test produces an XML output file with the expected
     default name if no name is explicitly specified.
     """
@@ -309,7 +311,8 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase):
     self.assertTrue(os.path.isfile(output_file))
 
   def testSuppressedXmlOutput(self):
-    """
+    """Verifies XML output is suppressed if default listener is shut down.
+
     Tests that no XML file is generated if the default XML listener is
     shut down before RUN_ALL_TESTS is invoked.
     """
@@ -363,11 +366,18 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase):
         extra_env={SHARD_INDEX_ENV_VAR: '0',
                    TOTAL_SHARDS_ENV_VAR: '10'})
 
-  def _GetXmlOutput(self, gtest_prog_name, extra_args, extra_env,
-                    expected_exit_code):
-    """
-    Returns the xml output generated by running the program gtest_prog_name.
+  def _GetXmlOutput(
+      self, gtest_prog_name, extra_args, extra_env, expected_exit_code
+  ):
+    """Returns the XML output generated by running the program gtest_prog_name.
+
     Furthermore, the program's exit code must be expected_exit_code.
+
+    Args:
+      gtest_prog_name: Program to run.
+      extra_args: Optional arguments to pass to program.
+      extra_env: Optional environment variables to set.
+      expected_exit_code: Expected exit code from running gtest_prog_name.
     """
     xml_path = os.path.join(gtest_test_utils.GetTempDir(),
                             gtest_prog_name + 'out.xml')
@@ -398,11 +408,19 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase):
 
   def _TestXmlOutput(self, gtest_prog_name, expected_xml,
                      expected_exit_code, extra_args=None, extra_env=None):
-    """
+    """Asserts that the XML document matches.
+
     Asserts that the XML document generated by running the program
     gtest_prog_name matches expected_xml, a string containing another
     XML document.  Furthermore, the program's exit code must be
     expected_exit_code.
+
+    Args:
+      gtest_prog_name: Program to run.
+      expected_xml: Path to XML document to match.
+      expected_exit_code: Expected exit code from running gtest_prog_name.
+      extra_args: Optional arguments to pass to program.
+      extra_env: Optional environment variables to set.
     """
 
     actual = self._GetXmlOutput(gtest_prog_name, extra_args or [],
diff --git a/googletest/test/gtest_xml_test_utils.py b/googletest/test/gtest_xml_test_utils.py
index ae41bba..567a314 100755
--- a/googletest/test/gtest_xml_test_utils.py
+++ b/googletest/test/gtest_xml_test_utils.py
@@ -40,9 +40,9 @@ class GTestXMLTestCase(gtest_test_utils.TestCase):
   Base class for tests of Google Test's XML output functionality.
   """
 
-
   def AssertEquivalentNodes(self, expected_node, actual_node):
-    """
+    """Asserts that actual_node is equivalent to expected_node.
+
     Asserts that actual_node (a DOM node object) is equivalent to
     expected_node (another DOM node object), in that either both of
     them are CDATA nodes and have the same value, or both are DOM
@@ -58,6 +58,10 @@ class GTestXMLTestCase(gtest_test_utils.TestCase):
        CDATA sections) as expected_node.  Note that we ignore the
        order of the children as they are not guaranteed to be in any
        particular order.
+
+    Args:
+      expected_node: expected DOM node object
+      actual_node: actual DOM node object
     """
 
     if expected_node.nodeType == Node.CDATA_SECTION_NODE:
@@ -126,18 +130,24 @@ class GTestXMLTestCase(gtest_test_utils.TestCase):
   }
 
   def _GetChildren(self, element):
-    """
-    Fetches all of the child nodes of element, a DOM Element object.
-    Returns them as the values of a dictionary keyed by the IDs of the
-    children.  For <testsuites>, <testsuite>, <testcase>, and <property>
-    elements, the ID is the value of their "name" attribute; for <failure>
-    elements, it is the value of the "message" attribute; for <properties>
-    elements, it is the value of their parent's "name" attribute plus the
-    literal string "properties"; CDATA sections and non-whitespace
-    text nodes are concatenated into a single CDATA section with ID
-    "detail".  An exception is raised if any element other than the above
-    four is encountered, if two child elements with the same identifying
-    attributes are encountered, or if any other type of node is encountered.
+    """Fetches all of the child nodes of element, a DOM Element object.
+
+    Returns them as the values of a dictionary keyed by the IDs of the children.
+    For <testsuites>, <testsuite>, <testcase>, and <property> elements, the ID
+    is the value of their "name" attribute; for <failure> elements, it is the
+    value of the "message" attribute; for <properties> elements, it is the value
+    of their parent's "name" attribute plus the literal string "properties";
+    CDATA sections and non-whitespace text nodes are concatenated into a single
+    CDATA section with ID "detail".  An exception is raised if any element other
+    than the above four is encountered, if two child elements with the same
+    identifying attributes are encountered, or if any other type of node is
+    encountered.
+
+    Args:
+      element: DOM Element object
+
+    Returns:
+      Dictionary where keys are the IDs of the children.
     """
 
     children = {}
@@ -171,7 +181,8 @@ class GTestXMLTestCase(gtest_test_utils.TestCase):
     return children
 
   def NormalizeXml(self, element):
-    """
+    """Normalizes XML that may change from run to run.
+
     Normalizes Google Test's XML output to eliminate references to transient
     information that may change from run to run.
 
@@ -188,6 +199,9 @@ class GTestXMLTestCase(gtest_test_utils.TestCase):
        file's basename and a single asterisk for the line number.
     *  The directory names in file paths are removed.
     *  The stack traces are removed.
+
+    Args:
+      element: DOM element to normalize
     """
 
     if element.tagName == 'testcase':