Permalink
Browse files

DocumentationAPI: Add `MalformedComment`

`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 16, 2017
1 parent 35750ae commit 0f8158322cc2bedc14967ea8d3d03bfad908f659
@@ -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(
@@ -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
@@ -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):
@@ -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
@@ -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>' +
@@ -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):
@@ -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)
@@ -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...)
@@ -1,5 +1,3 @@
/**module comment
* hello world
*/
/** Aborts...
@@ -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.