Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix #309 Missing helptext for multiline argument #335

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Fix #309 Missing helptext for multiline argument #335

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9496fc7
Fix issue #309
xosnos Apr 24, 2021
6ad659e
Extend fix for issue #309
xosnos Apr 24, 2021
64d4a1a
Fix style
xosnos Apr 24, 2021
434fffa
Make changes based on suggestions from @MichaelCG8
xosnos Apr 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
32 changes: 27 additions & 5 deletions fire/docstrings.py
View file
Open in desktop
Expand Up @@ -322,6 +322,21 @@ def _is_arg_name(name):
re.match(arg_pattern, name)
return re.match(arg_pattern, name) is not None

def _is_arg_type(type_):
"""Returns whether type_ is a valid arg type.

Example:
_is_arg_type("(int)") == True

Args:
type_: The type of potential arg.
Returns:
True if type_ looks like an arg type, False otherwise.
"""
type_ = type_.strip()
return (re.match(r'^[(]\w*[)]$', type_) or
re.match(r'^[{]\w*[}]$', type_) or
re.match(r'^[\[]\w*[\]]$', type_))

def _as_arg_name_and_type(text):
"""Returns text as a name and type, if text looks like an arg name and type.
Expand All @@ -338,7 +353,7 @@ def _as_arg_name_and_type(text):
tokens = text.split()
if len(tokens) < 2:
return None
if _is_arg_name(tokens[0]):
if _is_arg_name(tokens[0]) and _is_arg_type(tokens[1]):
type_token = ' '.join(tokens[1:])
type_token = type_token.lstrip('{([').rstrip('])}')
return tokens[0], type_token
Expand Down Expand Up @@ -391,22 +406,29 @@ 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:
first, second = split_line # first is either the "arg" or "arg (type)"
if _is_arg_name(first.strip()):
# first is any of the three: "arg", "arg (type)", or
# text before a colon in a continued line of an arg description
first, second = split_line
# indent_check determines if line is a new arg or
# a continuation of current arg description
indent_check = line_info.indentation <= state.section.line1_indentation
if _is_arg_name(first.strip()) and (
state.current_arg is None or indent_check):
arg = _get_or_create_arg_by_name(state, first.strip())
arg.description.lines.append(second.strip())
state.current_arg = arg
else:
arg_name_and_type = _as_arg_name_and_type(first)
if arg_name_and_type:
if arg_name_and_type and (
state.current_arg is None or indent_check):
arg_name, type_str = arg_name_and_type
arg = _get_or_create_arg_by_name(state, arg_name)
arg.type.lines.append(type_str)
arg.description.lines.append(second.strip())
state.current_arg = arg
else:
if state.current_arg:
state.current_arg.description.lines.append(split_line[0])
state.current_arg.description.lines.append(first + ':' + second)
else:
if state.current_arg:
state.current_arg.description.lines.append(split_line[0])
Expand Down
117 changes: 114 additions & 3 deletions fire/docstrings_test.py
View file
Open in desktop
Expand Up @@ -153,7 +153,7 @@ def test_google_format_multiline_arg_description(self):
Args:
param1 (int): The first parameter.
param2 (str): The second parameter. This has a lot of text, enough to
cover two lines.
cover two lines.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
Expand All @@ -164,8 +164,119 @@ def test_google_format_multiline_arg_description(self):
ArgInfo(name='param1', type='int',
description='The first parameter.'),
ArgInfo(name='param2', type='str',
description='The second parameter. This has a lot of text, '
'enough to cover two lines.'),
description='The second parameter. This has a lot of text'
', enough to cover two lines.'),
],
)
self.assertEqual(expected_docstring_info, docstring_info)

def test_google_format_multiline_arg_description_colon(self):
docstring = """Docstring summary.

This is a longer description of the docstring. It spans multiple lines, as
is allowed.

Args:
param1 (int): The first parameter.
param2 (str): The second parameter. This has a lot of text, enough to
cover two lines. This description also contains a : colon.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='Docstring summary.',
description='This is a longer description of the docstring. It spans '
'multiple lines, as\nis allowed.',
args=[
ArgInfo(name='param1', type='int',
description='The first parameter.'),
ArgInfo(name='param2', type='str',
description='The second parameter. This has a lot of text'
', enough to cover two lines. This '
'description also contains a : colon.'),
],
)
self.assertEqual(expected_docstring_info, docstring_info)

def test_google_format_multiline_arg_description_colon_wrapped(self):
docstring = """Docstring summary.

This is a longer description of the docstring. It spans multiple lines, as
is allowed.

Args:
param1 (int): The first parameter.
param2 (str): The second parameter. This description contains a
colon : after the first word of the wrapped line.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='Docstring summary.',
description='This is a longer description of the docstring. It spans '
'multiple lines, as\nis allowed.',
args=[
ArgInfo(name='param1', type='int',
description='The first parameter.'),
ArgInfo(name='param2', type='str',
description='The second parameter. This description '
'contains a colon : after the first word '
'of the wrapped line.'),
],
)
self.assertEqual(expected_docstring_info, docstring_info)

def test_google_format_multiline_arg_description_colon_parenthesis(self):
docstring = """Docstring summary.

This is a longer description of the docstring. It spans multiple lines, as
is allowed.

Args:
param1 (int): The first parameter.
param2 (str): The second parameter. This description contains a
colon (and): parenthesis after the first word of the wrapped line.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='Docstring summary.',
description='This is a longer description of the docstring. It spans '
'multiple lines, as\nis allowed.',
args=[
ArgInfo(name='param1', type='int',
description='The first parameter.'),
ArgInfo(name='param2', type='str',
description='The second parameter. This description '
'contains a colon (and): parenthesis after '
'the first word of the wrapped line.'),
],
)
self.assertEqual(expected_docstring_info, docstring_info)

def test_google_format_multiline_arg_description_colon_three_lines(self):
docstring = """Docstring summary.

This is a longer description of the docstring. It spans multiple lines, as
is allowed.

Args:
param1 (int): The first parameter.
param2 (str): The second parameter. This has a lot of text, enough to
cover three lines. This description also contains a colon
here : on this line of the argument description.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='Docstring summary.',
description='This is a longer description of the docstring. It spans '
'multiple lines, as\nis allowed.',
args=[
ArgInfo(name='param1', type='int',
description='The first parameter.'),
ArgInfo(name='param2', type='str',
description='The second parameter. This has a lot of text'
', enough to cover three lines. This '
'description also contains a colon '
'here : on this line of the argument '
'description.'),
],
)
self.assertEqual(expected_docstring_info, docstring_info)
Expand Down