Permalink
Browse files

DocumentationStyleBear: Add blankline support

DocumentationStyleBear now checks for blankline
before and after the docstring and fixes them.

Related to coala/coala#4200
  • Loading branch information...
damngamerz committed Aug 19, 2017
1 parent 1e451a2 commit 89b5913837d54279a928d3ef3c62995f4e9c2648
@@ -21,15 +21,15 @@ class DocumentationStyleBear(DocBaseClass, LocalBear):
CAN_FIX = {'Documentation'}
def process_documentation(self,
parsed,
doc_comment: DocumentationComment,
allow_missing_func_desc: str=False,
indent_size: int=4,
expand_one_liners: str=False):
"""
This fixes the parsed documentation comment.
:param parsed:
Contains parsed documentation comment.
:param doc_comment:
Contains instance of DocumentationComment.
:param allow_missing_func_desc:
When set ``True`` this will allow functions with missing
descriptions, allowing functions to start with params.
@@ -40,6 +40,7 @@ def process_documentation(self,
:return:
A tuple of fixed parsed documentation comment and warning_desc.
"""
parsed = doc_comment.parse()
# Assuming that the first element is always the only main
# description.
metadata = iter(parsed)
@@ -92,7 +93,36 @@ def process_documentation(self,
new_desc = new_desc.rstrip() + '\n'
new_metadata.append(m._replace(desc=new_desc.lstrip(' ')))
return (new_metadata, warning_desc)
new_comment = DocumentationComment.from_metadata(
new_metadata, doc_comment.docstyle_definition,
doc_comment.marker, doc_comment.indent, doc_comment.position)
# Instantiate default padding.
class_padding = doc_comment.docstyle_definition.class_padding
function_padding = doc_comment.docstyle_definition.function_padding
# Check if default padding exist in the coalang file.
if (class_padding != DocstyleDefinition.ClassPadding('', '') and
function_padding != DocstyleDefinition.FunctionPadding(
'', '')):
# Check docstring_type
if doc_comment.docstring_type == 'class':
new_comment.top_padding = class_padding.top_padding
new_comment.bottom_padding = class_padding.bottom_padding
elif doc_comment.docstring_type == 'function':
new_comment.top_padding = function_padding.top_padding
new_comment.bottom_padding = function_padding.bottom_padding
else:
# Keep paddings as they are originally.
new_comment.top_padding = doc_comment.top_padding
new_comment.bottom_padding = doc_comment.bottom_padding
else:
# If there's no default paddings defined. Keep padding as
# they are originally.
new_comment.top_padding = doc_comment.top_padding
new_comment.bottom_padding = doc_comment.bottom_padding
return (new_comment, warning_desc)
def run(self, filename, file, language: str,
docstyle: str='default', allow_missing_func_desc: str=False,
@@ -131,18 +161,15 @@ def run(self, filename, file, language: str,
file=filename,
line=doc_comment.line + 1)
else:
parsed = doc_comment.parse()
(new_metadata, warning_desc) = self.process_documentation(
parsed, allow_missing_func_desc, indent_size,
expand_one_liners)
new_comment = DocumentationComment.from_metadata(
new_metadata, doc_comment.docstyle_definition,
doc_comment.marker, doc_comment.indent,
doc_comment.position)
if new_comment != doc_comment:
(new_comment, warning_desc) = self.process_documentation(
doc_comment, allow_missing_func_desc,
indent_size, expand_one_liners)
# Cache cleared so a fresh docstring is assembled
doc_comment.assemble.cache_clear()
# Assembled docstring check, because paddings are only
# amended after assemble()
if new_comment.assemble() != doc_comment.assemble():
# Something changed, let's apply a result.
diff = self.generate_diff(file, doc_comment, new_comment)
yield Result(
@@ -78,6 +78,8 @@ class DocumentationStyleBearTest(unittest.TestCase):
test_good2 = test('good_file2.py.test', 'good_file2.py.test')
test_good3 = test('good_file3.py.test', 'good_file3.py.test',
{'allow_missing_func_desc': 'True'})
test_bad_java = test('bad_file.java.test', 'bad_file.java.test.correct',
{'language': 'java'})
test_malformed_comment_python = test_MalformedComment(
['"""\n',
@@ -0,0 +1,15 @@
class HelloWorld {
/**
*Java docstyle test.
*There's no official standard for how paddings are in java.
*Hence, in this case paddings are preserved as original.
*
*@param name the name to which to say hello
*@raises IOException throws IOException
*@return the concatenated string
*/
public String sayHello(String name) throws IOException {
return "Hello, " + name;
}
}
@@ -0,0 +1,18 @@
class HelloWorld {
/**
*Java docstyle test.
*There's no official standard for how paddings are in java.
*Hence, in this case paddings are preserved as original.
*
*@param name
* the name to which to say hello
*@raises IOException
* throws IOException
*@return
* the concatenated string
*/
public String sayHello(String name) throws IOException {
return "Hello, " + name;
}
}
@@ -14,6 +14,7 @@ def docstring_testcase(dummy):
def docstring_singleliner():
""" This is singleliner docstring. """
return None
def docstring_inline():
"""
@@ -17,7 +17,7 @@ def docstring_singleliner():
"""
This is singleliner docstring.
"""
return None
def docstring_inline():
"""
@@ -30,9 +30,11 @@ class docstring_if_indented():
"""
This is `if` indented block function.
"""
return None
else:
def hello_venus(self):
"""This is `if` indented block function."""
return None
def docstring_inner_function(dummy):
@@ -41,11 +41,13 @@ class docstring_if_indented():
"""
This is `if` indented block function.
"""
return None
else:
def hello_venus(self):
"""
This is `if` indented block function.
"""
return None
def docstring_inner_function(dummy):
@@ -7,3 +7,28 @@ def docstring_missing_descriptions(a, b, x):
:return:"""
return a * x + b
class docstring_class_improper_paddings(dummy):
"""
Docstring has improper paddings. `class` type docstrings
should be followed by 1 blank line at the bottom.
:param dummy:
dummy description.
"""
def docstring_function_improper_paddings:
"""
Docstring has improper paddings. `function` type docstrings
should never be followed by any blank lines.
:return:
None
"""
return None
@@ -8,5 +8,24 @@ def docstring_missing_descriptions(a, b, x):
:param x:
:return:
"""
return a * x + b
class docstring_class_improper_paddings(dummy):
"""
Docstring has improper paddings. `class` type docstrings
should be followed by 1 blank line at the bottom.
:param dummy:
dummy description.
"""
def docstring_function_improper_paddings:
"""
Docstring has improper paddings. `function` type docstrings
should never be followed by any blank lines.
:return:
None
"""
return None
@@ -4,5 +4,6 @@ def docstring_missing_description(dummy):
a function starting with `param`
in this case allow_missing_func_desc = True
"""
return None
"""This is one-liner docstring"""

0 comments on commit 89b5913

Please sign in to comment.