Don't strip whitespace when collecting descriptions in docstring

PiperOrigin-RevId: 260030371
Change-Id: Id307fa5ca4c77e07290928daea6b3e4291e1c0e6

Author: EvanJuV

fire/docstrings.py

@@ -56,6 +56,7 @@
 
 import collections
 import re
+import textwrap
 
 import enum
 
@@ -179,7 +180,10 @@ def parse(docstring):
     _consume_line(line_info, state)
 
   summary = ' '.join(state.summary.lines) if state.summary.lines else None
-  description = _join_lines(state.description.lines)
+  state.description.lines = _strip_blank_lines(state.description.lines)
+  description = textwrap.dedent('\n'.join(state.description.lines))
+  if not description:
+    description = None
   returns = _join_lines(state.returns.lines)
   yields = _join_lines(state.yields.lines)
   raises = _join_lines(state.raises.lines)
@@ -203,6 +207,32 @@ def parse(docstring):
   )
 
 
+def _strip_blank_lines(lines):
+  """Removes lines containing only blank characters before and after the text.
+
+  Args:
+    lines: A list of lines.
+  Returns:
+    A list of lines without trailing or leading blank lines.
+  """
+  # Find the first non-blank line.
+  start = 0
+  while lines and _is_blank(lines[start]):
+    start += 1
+
+  lines = lines[start:]
+
+  # Remove trailing blank lines.
+  while lines and _is_blank(lines[-1]):
+    lines.pop()
+
+  return lines
+
+
+def _is_blank(line):
+  return not line or line.isspace()
+
+
 def _join_lines(lines):
   """Joins lines with the appropriate connective whitespace.
 
@@ -391,7 +421,7 @@ def _consume_line(line_info, state):
     else:
       # We're past the end of the summary.
       # Additions now contribute to the description.
-      state.description.lines.append(line_info.remaining)
+      state.description.lines.append(line_info.remaining_raw)
   else:
     state.summary.permitted = False
 
@@ -470,6 +500,7 @@ def _create_line_info(line, next_line):
   line_info = Namespace()  # TODO(dbieber): Switch to an explicit class.
   line_info.line = line
   line_info.stripped = line.strip()
+  line_info.remaining_raw = line_info.line
   line_info.remaining = line_info.stripped
   line_info.indentation = len(line) - len(line.lstrip())
   line_info.next.line = next_line
@@ -497,20 +528,23 @@ def _update_section_state(line_info, state):
     state.section.format = Formats.GOOGLE
     state.section.title = google_section
     line_info.remaining = _get_after_google_header(line_info)
+    line_info.remaining_raw = line_info.remaining
     section_updated = True
 
   rst_section = _rst_section(line_info)
   if rst_section:
     state.section.format = Formats.RST
     state.section.title = rst_section
     line_info.remaining = _get_after_directive(line_info)
+    line_info.remaining_raw = line_info.remaining
     section_updated = True
 
   numpy_section = _numpy_section(line_info)
   if numpy_section:
     state.section.format = Formats.NUMPY
     state.section.title = numpy_section
     line_info.remaining = ''
+    line_info.remaining_raw = line_info.remaining
     section_updated = True
 
   if section_updated:

fire/docstrings_test.py

@@ -131,7 +131,7 @@ def test_google_format_typed_args_and_returns(self):
     expected_docstring_info = DocstringInfo(
         summary='Docstring summary.',
         description='This is a longer description of the docstring. It spans '
-        'multiple lines, as is allowed.',
+        'multiple lines, as\nis allowed.',
         args=[
             ArgInfo(name='param1', type='int',
                     description='The first parameter.'),
@@ -159,7 +159,7 @@ def test_rst_format_typed_args_and_returns(self):
     expected_docstring_info = DocstringInfo(
         summary='Docstring summary.',
         description='This is a longer description of the docstring. It spans '
-        'across multiple lines.',
+        'across multiple\nlines.',
         args=[
             ArgInfo(name='arg1', type='str',
                     description='Description of arg1.'),
@@ -193,7 +193,7 @@ def test_numpy_format_typed_args_and_returns(self):
     expected_docstring_info = DocstringInfo(
         summary='Docstring summary.',
         description='This is a longer description of the docstring. It spans '
-        'across multiple lines.',
+        'across multiple\nlines.',
         args=[
             ArgInfo(name='param1', type='int',
                     description='The first parameter.'),
@@ -217,7 +217,7 @@ def test_multisection_docstring(self):
     expected_docstring_info = DocstringInfo(
         summary='Docstring summary.',
         description='This is the first section of a docstring description.\n\n'
-        'This is the second section of a docstring description. This docstring '
+        'This is the second section of a docstring description. This docstring\n'
         'description has just two sections.',
     )
     self.assertEqual(docstring_info, expected_docstring_info)
@@ -232,6 +232,12 @@ def test_ill_formed_docstring(self):
     """
     docstrings.parse(docstring)
 
+  def test_strip_blank_lines(self):
+    lines = ['   ', '  foo  ', '   ']
+    expected_output = ['  foo  ']
+
+    self.assertEqual(docstrings._strip_blank_lines(lines), expected_output)
+
 
 if __name__ == '__main__':
   testutils.main()

fire/test_components.py

@@ -440,3 +440,20 @@ def function_with_varargs(arg1, arg2, arg3=1, *varargs):  # pylint: disable=keyw
 def function_with_keyword_arguments(arg1, arg2=3, **kwargs):
   del arg2  # Unused.
   return arg1, kwargs
+
+
+def fn_with_code_in_docstring():
+  """This has code in the docstring.
+
+
+
+  Example:
+    x = fn_with_code_in_docstring()
+    indentation_matters = True
+
+
+
+  Returns:
+    True.
+  """
+  return True