@@ -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 ("""\
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 ,
