Docstring description multiline parsing

fire/docstrings.py

@@ -177,13 +177,22 @@ def parse(docstring):
   state.returns.lines = []
   state.yields.lines = []
   state.raises.lines = []
+  state.line1 = None
+  state.line1_length = None
+  state.line2_first_word_length = None
+  state.line2_length = None
+  state.line3_first_word_length = None
+  state.max_line_length = 0
 
   for index, line in enumerate(lines):
     has_next = index + 1 < lines_len
     previous_line = lines[index - 1] if index > 0 else None
     next_line = lines[index + 1] if has_next else None
     line_info = _create_line_info(line, next_line, previous_line)
     _consume_line(line_info, state)
+
+  if state.line2_length:
+    _merge_if_long_arg(state)
 
   summary = ' '.join(state.summary.lines) if state.summary.lines else None
   state.description.lines = _strip_blank_lines(state.description.lines)
@@ -253,7 +262,7 @@ def _join_lines(lines):
   # TODO(dbieber): Add parameters for variations in whitespace handling.
   if not lines:
     return None
-
+   
   started = False
   group_texts = []  # Full text of each section.
   group_lines = []  # Lines within the current section.
@@ -269,7 +278,7 @@ def _join_lines(lines):
         group_lines = []
 
   if group_lines:  # Process the final group.
-    group_text = ' '.join(group_lines)
+    group_text = '\n'.join(group_lines)
     group_texts.append(group_text)
 
   return '\n\n'.join(group_texts)
@@ -391,6 +400,9 @@ def _consume_google_args_line(line_info, state):
   """Consume a single line from a Google args section."""
   split_line = line_info.remaining.split(':', 1)
   if len(split_line) > 1:
+    state.line1 = line_info.line
+    state.line1_length = len(line_info.line)
+    state.max_line_length = max(state.max_line_length, state.line1_length)
     first, second = split_line  # first is either the "arg" or "arg (type)"
     if _is_arg_name(first.strip()):
       arg = _get_or_create_arg_by_name(state, first.strip())
@@ -410,6 +422,65 @@ def _consume_google_args_line(line_info, state):
   else:
     if state.current_arg:
       state.current_arg.description.lines.append(split_line[0])
+      state.max_line_length = max(state.max_line_length, len(line_info.line))
+      if line_info.previous.line == state.line1: # check for line2
+        state.line2_first_word_length = len(line_info.line.strip().split(' ')[0])
+        state.line2_length = len(line_info.line)
+        if line_info.next.line: #check for line3
+          state.line3_first_word_length = len(line_info.next.line.strip().split(' ')[0])
+
+
+def _merge_if_long_arg(state):
+  """Merges first two lines of the description if the arg name is too long.
+
+  Args:
+    state: The state of the docstring parser.
+  """
+  apparent_max_line_length = roundup(state.max_line_length)
+  long_arg_name = roundup(len(state.current_arg.name), 5) >= 0.5 * apparent_max_line_length
+  if long_arg_name and state.line2_first_word_length and state.line3_first_word_length:
+    line1_intentionally_short = (state.line1_length + state.line2_first_word_length) <= apparent_max_line_length
+    line2_intentionally_short = (state.line2_length + state.line3_first_word_length) <= apparent_max_line_length
+    line1_intentionally_long = state.line1_length >= 1.05 * apparent_max_line_length
+    line2_intentionally_long = state.line2_length >= 1.05 * apparent_max_line_length
+    if not line1_intentionally_short and not line1_intentionally_long and not line2_intentionally_short and not line2_intentionally_long:
+      _merge_line1_line2(state.current_arg.description.lines)
+
+
+def _merge_line1_line2(lines):
+  """Merges the first two lines of a list of strings.
+
+  Example:
+    _merge_line1_line2(["oh","no","bro"]) == ["oh no","bro"]
+
+  Args:
+    lines: a list of strings representing each line.
+  Returns:
+    the same list but with the first two lines of the list now merged as one line. 
+  """
+  merged_line = lines[0] + " " + lines[1]
+  lines[0] = merged_line
+  lines.pop(1)
+  return lines
+
+
+def roundup(number, multiple=10):
+  """Rounds a number to the nearst multiple.
+
+  Example:
+    roundup(72) == 80
+
+  Args:
+    number: an interger type variable.
+    multiple: nearst multiple to round up to
+  Returns:
+    An interger value.
+  """
+  remainder = number % multiple
+  if remainder == 0:
+    return number #already rounded
+  else:
+    return number + (multiple - remainder)
 
 
 def _consume_line(line_info, state):

fire/docstrings_test.py

@@ -165,7 +165,7 @@ def test_google_format_multiline_arg_description(self):
                     description='The first parameter.'),
             ArgInfo(name='param2', type='str',
                     description='The second parameter. This has a lot of text, '
-                                'enough to cover two lines.'),
+                                'enough to\ncover two lines.'),
         ],
     )
     self.assertEqual(expected_docstring_info, docstring_info)
@@ -229,7 +229,7 @@ def test_numpy_format_typed_args_and_returns(self):
                     description='The second parameter.'),
         ],
         # TODO(dbieber): Support return type.
-        returns='bool True if successful, False otherwise.',
+        returns='bool\nTrue if successful, False otherwise.',
     )
     self.assertEqual(expected_docstring_info, docstring_info)
 
@@ -257,7 +257,7 @@ def test_numpy_format_multiline_arg_description(self):
                     description='The first parameter.'),
             ArgInfo(name='param2', type='str',
                     description='The second parameter. This has a lot of text, '
-                                'enough to cover two lines.'),
+                                'enough to cover two\nlines.'),
         ],
     )
     self.assertEqual(expected_docstring_info, docstring_info)