Skip to content

Commit

Permalink
DocumentationAPI: Add MalformedComment
Browse files Browse the repository at this point in the history
`MalformedComment` is the new error handling mechanism
in DocumentationAPI. Which will help in yielding a
subsequent `RESULT` with a beautiful message in the bear.

Closes #4548
  • Loading branch information
damngamerz committed Aug 17, 2017
1 parent 35750ae commit 0f81583
Show file tree
Hide file tree
Showing 7 changed files with 91 additions and 17 deletions.
5 changes: 3 additions & 2 deletions coalib/bearlib/languages/documentation/DocBaseClass.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,9 @@ def extract(content, language, docstyle):
defined in given docstyle.
:raises ValueError: Raised when a docstyle definition setting
has an invalid format.
:return: An iterator returning each
DocumentationComment found in the content.
:return: An iterator returning instances of
DocumentationComment or MalformedComment
found in the content.
"""
docstyle_definition = DocstyleDefinition.load(language, docstyle)
return extract_documentation_with_markers(
Expand Down
26 changes: 26 additions & 0 deletions coalib/bearlib/languages/documentation/DocumentationComment.py
Original file line number Diff line number Diff line change
Expand Up @@ -284,3 +284,29 @@ def assemble(self):
assembled = ('\n' * self.top_padding + assembled +
'\n' * self.bottom_padding)
return assembled


class MalformedComment:
"""
The MalformedComment holds information about the errors generated by the
DocumentationExtraction, DocumentationComment, DocstyleDefinition and
DocBaseClass.
When these classes are unable to parse certain docstrings, an instance
of MalformedComment will be returned instead of DocumentationComment.
"""

def __init__(self, message, line):
"""
Instantiate a MalformedComment, which contains the information about
the error: a message explaining the behaviour and a line no where the
error has occured.
:param message:
Contains the message about the error.
:param line:
Contains the current line of the docstring where the error has
occured.
"""
self.message = message
self.line = line
19 changes: 16 additions & 3 deletions coalib/bearlib/languages/documentation/DocumentationExtraction.py
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
import re

from coalib.bearlib.languages.documentation.DocumentationComment import (
DocumentationComment)
DocumentationComment, MalformedComment)
from coalib.results.TextPosition import TextPosition
from textwrap import dedent


def _extract_doc_comment_simple(content, line, column, markers):
Expand Down Expand Up @@ -196,7 +197,16 @@ def _extract_doc_comment_from_line(content, line, column, regex,
doc = DocumentationComment(documentation, docstyle_definition,
indent, marker, position)

return end_line, end_column, doc
break

if doc_comment:
return end_line, end_column, doc
else:
malformed_comment = MalformedComment(dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), line)
return line + 1, 0, malformed_comment

return line + 1, 0, None

Expand Down Expand Up @@ -244,7 +254,10 @@ def extract_documentation_with_markers(content, docstyle_definition):
begin_regex,
marker_dict,
docstyle_definition)
if doc:

if doc and isinstance(doc, MalformedComment):
yield doc
elif doc:
# Ignore string literals
ignore_regex = re.compile(
'^\s*r?(?P<marker>' +
Expand Down
47 changes: 46 additions & 1 deletion tests/bearlib/languages/documentation/DocBaseClassTest.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,15 @@
from coalib.bearlib.languages.documentation.DocstyleDefinition import (
DocstyleDefinition)
from coalib.bearlib.languages.documentation.DocumentationComment import (
DocumentationComment)
DocumentationComment, MalformedComment)
from coalib.bearlib.languages.documentation.DocBaseClass import (
DocBaseClass)
from tests.bearlib.languages.documentation.TestUtils import (
load_testdata)
from coalib.results.TextPosition import TextPosition
from coalib.results.TextRange import TextRange
from coalib.results.Diff import Diff
from textwrap import dedent


class DocBaseClassTest(unittest.TestCase):
Expand Down Expand Up @@ -301,3 +302,47 @@ def test_DocBaseClass_process_documentation_not_implemented(self):
test_object = DocBaseClass()
self.assertRaises(NotImplementedError,
test_object.process_documentation)

def test_MalformedComment1_C(self):
data = ['/**\n',
'* A doc-comment aborted in the middle of writing\n',
'* This won\'t get parsed (hopefully...)\n']

expected = [dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), 0]

for doc_comment in DocBaseClass.extract(data, 'C', 'doxygen'):
self.assertEqual(
[doc_comment.message, doc_comment.line],
expected)

def test_MalformedComment2_CPP(self):
data = ['\n',
'/** Aborts...\n']

expected = [dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), 1]

for doc_comment in DocBaseClass.extract(data, 'CPP', 'doxygen'):
self.assertEqual(
[doc_comment.message, doc_comment.line],
expected)

def test_MalformedComment3_JAVA(self):
data = ['/**\n',
'* Markers are faulty\n',
'*/']

expected = [dedent("""\
Please check the docstring for faulty markers. A starting
marker has been found, but no instance of DocComment is
returned."""), 0]

for doc_comment in DocBaseClass.extract(data, 'JAVA', 'default'):
self.assertEqual(
[doc_comment.message, doc_comment.line],
expected)
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,3 @@ int myfield;
int foobar(int x) {
return x * x - x + 1;
}


/**
* A doc-comment aborted in the middle of writing
* This won't get parsed (hopefully...)
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
/**module comment
* hello world
*/

/** Aborts...
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,3 @@ int foobar(int x) {
* line2 */

/** */

/**
* A doc-comment aborted in the middle of writing
* This won't get parsed (hopefully...)

0 comments on commit 0f81583

Please sign in to comment.