robustify docstring parser to blank lines after section starts. Resolves #183

PiperOrigin-RevId: 260593779
Change-Id: Iab9052b9d56b24d65df9beb3ed8add68e2288926

Author: dbieber

fire/docstrings.py

@@ -188,14 +188,9 @@ def parse(docstring):
   yields = _join_lines(state.yields.lines)
   raises = _join_lines(state.raises.lines)
 
-  args = [
-      ArgInfo(
-          name=arg.name,
-          type=_cast_to_known_type(_join_lines(arg.type.lines)),
-          description=_join_lines(arg.description.lines),
-      )
-      for arg in state.args
-  ]
+  args = [ArgInfo(
+      name=arg.name, type=_cast_to_known_type(_join_lines(arg.type.lines)),
+      description=_join_lines(arg.description.lines)) for arg in state.args]
 
   return DocstringInfo(
       summary=summary,
@@ -503,10 +498,12 @@ def _create_line_info(line, next_line):
   line_info.remaining_raw = line_info.line
   line_info.remaining = line_info.stripped
   line_info.indentation = len(line) - len(line.lstrip())
+  # TODO(dbieber): If next_line is blank, use the next non-blank line.
   line_info.next.line = next_line
-  line_info.next.stripped = next_line.strip() if next_line else None
+  next_line_exists = next_line is not None
+  line_info.next.stripped = next_line.strip() if next_line_exists else None
   line_info.next.indentation = (
-      len(next_line) - len(next_line.lstrip()) if next_line else None)
+      len(next_line) - len(next_line.lstrip()) if next_line_exists else None)
   # Note: This counts all whitespace equally.
   return line_info
 

fire/docstrings_test.py

@@ -34,7 +34,7 @@ def test_one_line_simple(self):
     expected_docstring_info = DocstringInfo(
         summary='A simple one line docstring.',
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_one_line_simple_whitespace(self):
     docstring = """
@@ -44,7 +44,7 @@ def test_one_line_simple_whitespace(self):
     expected_docstring_info = DocstringInfo(
         summary='A simple one line docstring.',
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_one_line_too_long(self):
     # pylint: disable=line-too-long
@@ -57,7 +57,7 @@ def test_one_line_too_long(self):
         'a little too long so it keeps going well beyond a reasonable length '
         'for a one-liner.',
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_one_line_runs_over(self):
     # pylint: disable=line-too-long
@@ -70,7 +70,7 @@ def test_one_line_runs_over(self):
         summary='A one line docstring thats both a little too verbose and '
         'a little too long so it runs onto a second line.',
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_one_line_runs_over_whitespace(self):
     docstring = """
@@ -82,7 +82,7 @@ def test_one_line_runs_over_whitespace(self):
         summary='A one line docstring thats both a little too verbose and '
         'a little too long so it runs onto a second line.',
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_google_format_args_only(self):
     docstring = """One line description.
@@ -99,7 +99,7 @@ def test_google_format_args_only(self):
             ArgInfo(name='arg2', description='arg2_description'),
         ]
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_google_format_arg_named_args(self):
     docstring = """
@@ -112,7 +112,7 @@ def test_google_format_arg_named_args(self):
             ArgInfo(name='args', description='arg_description'),
         ]
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_google_format_typed_args_and_returns(self):
     docstring = """Docstring summary.
@@ -140,7 +140,7 @@ def test_google_format_typed_args_and_returns(self):
         ],
         returns='bool: The return value. True for success, False otherwise.'
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_rst_format_typed_args_and_returns(self):
     docstring = """Docstring summary.
@@ -169,7 +169,7 @@ def test_rst_format_typed_args_and_returns(self):
         returns='int -- description of the return value.',
         raises='AttributeError, KeyError',
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_numpy_format_typed_args_and_returns(self):
     docstring = """Docstring summary.
@@ -203,7 +203,7 @@ def test_numpy_format_typed_args_and_returns(self):
         # TODO(dbieber): Support return type.
         returns='bool True if successful, False otherwise.',
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
 
   def test_multisection_docstring(self):
     docstring = """Docstring summary.
@@ -222,7 +222,20 @@ def test_multisection_docstring(self):
         '\n'
         'description has just two sections.',
     )
-    self.assertEqual(docstring_info, expected_docstring_info)
+    self.assertEqual(expected_docstring_info, docstring_info)
+
+  def test_google_section_with_blank_first_line(self):
+    docstring = """Inspired by requests HTTPAdapter docstring.
+
+    :param x: Simple param.
+
+    Usage:
+
+      >>> import requests
+    """
+    docstring_info = docstrings.parse(docstring)
+    self.assertEqual('Inspired by requests HTTPAdapter docstring.',
+                     docstring_info.summary)
 
   def test_ill_formed_docstring(self):
     docstring = """Docstring summary.
@@ -238,7 +251,7 @@ def test_strip_blank_lines(self):
     lines = ['   ', '  foo  ', '   ']
     expected_output = ['  foo  ']
 
-    self.assertEqual(docstrings._strip_blank_lines(lines), expected_output)  # pylint: disable=protected-access
+    self.assertEqual(expected_output, docstrings._strip_blank_lines(lines))  # pylint: disable=protected-access
 
 
 if __name__ == '__main__':