DocStyleBear: Add MalformedComment support

DocStyleBear will use new error handling mechanism
`MalformedComment`. And yield a `RESULT` with a
message containing error details.

Related to coala/coala#4548

Author: damngamerz

bears/documentation/DocumentationStyleBear.py

@@ -1,5 +1,5 @@
 from coalib.bearlib.languages.documentation.DocumentationComment import (
-    DocumentationComment)
+    DocumentationComment, MalformedComment)
 from coalib.bearlib.languages.documentation.DocstyleDefinition import (
     DocstyleDefinition)
 from coalib.bearlib.languages.documentation.DocBaseClass import (
@@ -124,22 +124,29 @@ def run(self, filename, file, language: str,
         """
 
         for doc_comment in self.extract(file, language, docstyle):
-            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:
-                # Something changed, let's apply a result.
-                diff = self.generate_diff(file, doc_comment, new_comment)
-
-                yield Result(
+            if isinstance(doc_comment, MalformedComment):
+                yield Result.from_values(
                     origin=self,
-                    message=warning_desc,
-                    affected_code=(diff.range(filename),),
-                    diffs={filename: diff})
+                    message=doc_comment.message,
+                    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:
+                    # Something changed, let's apply a result.
+                    diff = self.generate_diff(file, doc_comment, new_comment)
+                    yield Result(
+                        origin=self,
+                        message=warning_desc,
+                        affected_code=(diff.range(filename),),
+                        diffs={filename: diff})

tests/documentation/DocumentationStyleBearTest.py

@@ -1,4 +1,5 @@
 from queue import Queue
+from textwrap import dedent
 import os.path
 import unittest
 
@@ -47,6 +48,24 @@ def test_function(self):
     return test_function
 
 
+def test_MalformedComment(test_data, message, optional_setting=None):
+    def test_MalformedComment_function(self):
+        arguments = {'language': 'python', 'docstyle': 'default'}
+        if optional_setting:
+            arguments.update(optional_setting)
+        section = Section('test-section')
+        for key, value in arguments.items():
+            section[key] = value
+        with execute_bear(
+                DocumentationStyleBear(section, Queue()),
+                'dummy_file',
+                test_data,
+                **arguments) as results:
+            self.assertEqual(results[0].message, message)
+
+    return test_MalformedComment_function
+
+
 class DocumentationStyleBearTest(unittest.TestCase):
     test_bad1 = test('bad_file.py.test', 'bad_file.py.test.correct')
     test_bad2 = test('bad_file2.py.test', 'bad_file2.py.test.correct',
@@ -59,3 +78,20 @@ 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_malformed_comment_python = test_MalformedComment(
+        ['"""\n',
+         'This will yield MalformedComment'],
+        dedent("""\
+             Please check the docstring for faulty markers. A starting
+             marker has been found, but no instance of DocComment is
+             returned."""))
+
+    test_malformed_comment_java = test_MalformedComment(
+        ['\n',
+         '/** This will yield MalformedComment\n'],
+        dedent("""\
+             Please check the docstring for faulty markers. A starting
+             marker has been found, but no instance of DocComment is
+             returned."""),
+        {'language': 'java'})