Permalink
Browse files

DocumentationStyleBear: Use DocBaseClass

DocumentationStyleBear uses new DocumentationAPI
DocBaseClass.

Closes #1927
  • Loading branch information...
damngamerz committed Jul 22, 2017
1 parent 554b877 commit 314dfdf50c54cdbef0db5305138a9f764c6ad612
Showing with 75 additions and 62 deletions.
  1. +75 −62 bears/documentation/DocumentationStyleBear.py
@@ -2,15 +2,15 @@
DocumentationComment)
from coalib.bearlib.languages.documentation.DocstyleDefinition import (
DocstyleDefinition)
from coalib.bearlib.languages.documentation.DocumentationExtraction import (
extract_documentation)
from coalib.bearlib.languages.documentation.DocBaseClass import (
DocBaseClass)
from coalib.bears.LocalBear import LocalBear
from coalib.results.Diff import Diff
from coalib.results.Result import Result
from coalib.results.TextRange import TextRange
from textwrap import dedent
class DocumentationStyleBear(LocalBear):
class DocumentationStyleBear(DocBaseClass, LocalBear):
LANGUAGES = {language for docstyle, language in
DocstyleDefinition.get_available_definitions()}
AUTHORS = {'The coala developers'}
@@ -20,6 +20,71 @@ class DocumentationStyleBear(LocalBear):
CAN_DETECT = {'Documentation'}
CAN_FIX = {'Documentation'}
def process_documentation(self, parsed, allow_missing_func_desc: str=False,
indent_size: int=4):
"""
This fixes the parsed documentation comment.
:param parsed:
Contains parsed documentation comment.
:param allow_missing_func_desc:
When set ``True`` this will allow functions with missing
descriptions, allowing functions to start with params.
:param indent_size:
Number of spaces per indentation level.
:return:
A tuple of fixed parsed documentation comment and warning_desc.
"""
# Assuming that the first element is always the only main
# description.
metadata = iter(parsed)
main_description = next(metadata)
if main_description.desc == '\n' and not allow_missing_func_desc:
# Triple quoted string literals doesn't look good. It breaks
# the line of flow. Hence we use dedent.
warning_desc = dedent("""\
Missing function description.
Please set allow_missing_func_desc = True to ignore this warning.
""")
else:
warning_desc = 'Documentation does not have correct style.'
# one empty line shall follow main description (except it's empty
# or no annotations follow).
if main_description.desc.strip() != '':
main_description = main_description._replace(
desc='\n' + main_description.desc.strip() + '\n' *
(1 if len(parsed) == 1 else 2))
new_metadata = [main_description]
for m in metadata:
# Split newlines and remove leading and trailing whitespaces.
stripped_desc = list(map(str.strip, m.desc.splitlines()))
if len(stripped_desc) == 0:
# Annotations should be on their own line, though no
# further description follows.
stripped_desc.append('')
else:
# Wrap parameter description onto next line if it follows
# annotation directly.
if stripped_desc[0] != '':
stripped_desc.insert(0, '')
# Indent with 4 spaces.
stripped_desc = ('' if line == '' else ' ' * indent_size
+ line for line in stripped_desc)
new_desc = '\n'.join(stripped_desc)
# Strip away trailing whitespaces and obsolete newlines (except
# one newline which is mandatory).
new_desc = new_desc.rstrip() + '\n'
new_metadata.append(m._replace(desc=new_desc.lstrip(' ')))
return (new_metadata, warning_desc)
def run(self, filename, file, language: str,
docstyle: str='default', allow_missing_func_desc: str=False,
indent_size: int=4):
@@ -46,72 +111,20 @@ def run(self, filename, file, language: str,
functions to start with params.
:param indent_size: Number of spaces per indentation level.
"""
for doc_comment in extract_documentation(file, language, docstyle):
parsed = doc_comment.parse()
metadata = iter(parsed)
# Assuming that the first element is always the only main
# description.
main_description = next(metadata)
for doc_comment in self.extract(file, language, docstyle):
parsed = doc_comment.parse()
if main_description.desc == '\n' and not allow_missing_func_desc:
warning_desc = """
Missing function description.
Please set allow_missing_func_desc = True to ignore this warning.
"""
else:
warning_desc = 'Documentation does not have correct style.'
# one empty line shall follow main description (except it's empty
# or no annotations follow).
if main_description.desc.strip() != '':
main_description = main_description._replace(
desc='\n' + main_description.desc.strip() + '\n' *
(1 if len(parsed) == 1 else 2))
new_metadata = [main_description]
for m in metadata:
# Split newlines and remove leading and trailing whitespaces.
stripped_desc = list(map(str.strip, m.desc.splitlines()))
if len(stripped_desc) == 0:
# Annotations should be on their own line, though no
# further description follows.
stripped_desc.append('')
else:
# Wrap parameter description onto next line if it follows
# annotation directly.
if stripped_desc[0] != '':
stripped_desc.insert(0, '')
# Indent with 4 spaces.
stripped_desc = ('' if line == '' else ' ' * indent_size
+ line for line in stripped_desc)
new_desc = '\n'.join(stripped_desc)
# Strip away trailing whitespaces and obsolete newlines (except
# one newline which is mandatory).
new_desc = new_desc.rstrip() + '\n'
new_metadata.append(m._replace(desc=new_desc.lstrip(' ')))
(new_metadata, warning_desc) = self.process_documentation(
parsed, allow_missing_func_desc, indent_size)
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:
# Something changed, let's apply a result.
diff = Diff(file)
# We need to update old comment positions, as `assemble()`
# prepends indentation for first line.
old_range = TextRange.from_values(
doc_comment.range.start.line,
1,
doc_comment.range.end.line,
doc_comment.range.end.column)
diff.replace(old_range, new_comment.assemble())
diff = self.generate_diff(file, doc_comment, new_comment)
yield Result(
origin=self,

0 comments on commit 314dfdf

Please sign in to comment.