DocstyleDefinition: Add metadata param

This metadata param will contain all of the required
documentation symbols that will be needed to parse the
documentation.

`param_start`, `param_end` and `return_sep` are the contents of
the metadata.

coalib/bearlib/languages/documentation/DocstyleDefinition.py

@@ -1,4 +1,4 @@
-from collections import Iterable
+from collections import Iterable, namedtuple
 import os.path
 
 from coala_utils.decorators import (
@@ -14,9 +14,12 @@ class DocstyleDefinition:
     documentation comment (for which language, documentation style/tool used
     etc.).
     """
+    Metadata = namedtuple("Metadata", ("param_start", "param_end",
+                                       "return_sep"))
 
     @enforce_signature
-    def __init__(self, language: str, docstyle: str, markers: (Iterable, str)):
+    def __init__(self, language: str, docstyle: str, markers: (Iterable, str),
+                 metadata: Metadata):
         """
         Instantiates a new DocstyleDefinition.
 
@@ -29,6 +32,11 @@ def __init__(self, language: str, docstyle: str, markers: (Iterable, str)):
                          or a single marker/delimiter string iterable that
                          identify a documentation comment. See ``markers``
                          property for more details on markers.
+        :param metadata: A namedtuple consisting of certain attributes that
+                         form the layout of the certain documentation comment
+                         e.g. ``param_start`` defining the start symbol of
+                         the parameter fields and ``param_end`` defining the
+                         end.
         """
         self._language = language.lower()
         self._docstyle = docstyle.lower()
@@ -47,6 +55,8 @@ def __init__(self, language: str, docstyle: str, markers: (Iterable, str)):
                 raise ValueError("Length of a given marker set was not 3 (was "
                                  "actually {}).".format(length))
 
+        self._metadata = metadata
+
     @property
     def language(self):
         """
@@ -106,6 +116,15 @@ def markers(self):
         """
         return self._markers
 
+    @property
+    def metadata(self):
+        """
+        A namedtuple of certain attributes present in the documentation.
+
+        These attributes are used to define parts of the documentation.
+        """
+        return self._metadata
+
     @classmethod
     @enforce_signature
     def load(cls, language: str, docstyle: str, coalang_dir=None):
@@ -152,9 +171,15 @@ def load(cls, language: str, docstyle: str, coalang_dir=None):
             raise KeyError("Language {!r} is not defined for docstyle {!r}."
                            .format(language, docstyle))
 
+        metadata_settings = ("param_start", "param_end", "return_sep")
+
+        metadata = cls.Metadata(*(str(docstyle_settings.get(req_setting, ""))
+                                  for req_setting in metadata_settings))
+
         marker_sets = (tuple(value)
                        for key, value in
-                       filter(lambda kv: not kv[0].startswith("comment"),
-                              docstyle_settings.contents.items()))
+                       docstyle_settings.contents.items()
+                       if key not in metadata_settings and
+                       not key.startswith("comment"))
 
-        return cls(language, docstyle, marker_sets)
+        return cls(language, docstyle, marker_sets, metadata)

coalib/bearlib/languages/documentation/default.coalang

@@ -1,9 +1,18 @@
 [PYTHON]
 doc-marker = """, , """
+param_start = :param\ # here's a space
+param_end = :
+return_sep = :return:
 
 [PYTHON3]
 doc-marker = """, , """
+param_start = :param\ # here's a space
+param_end = :
+return_sep = :return:
 
 [JAVA]
 doc-marker1 = /**, \ *, \ */
 doc-marker2 = /**, , \ */
+param_start = @param\ \ # here's a space
+param_end = \ # here's a space
+return_sep = @return\ # here's a space

coalib/bearlib/languages/documentation/doxygen.coalang

@@ -34,10 +34,16 @@ doc-marker6 = //!, //!, //!
 [PYTHON]
 doc-marker1 = """, , """
 doc-marker2 = \#\#, \#, \#
+param_start = @param\ # here's a space
+param_end = \ # here's a space
+return_sep = @return\ # here's a space
 
 [PYTHON3]
 doc-marker1 = """, , """
 doc-marker2 = \#\#, \#, \#
+param_start = @param\ # here's a space
+param_end = \ # here's a space
+return_sep = @return\ # here's a space
 
 [TCL]
 doc-marker = \#\#, \#, \#

tests/bearlib/languages/documentation/DocstyleDefinitionTest.py

@@ -8,49 +8,68 @@
 
 class DocstyleDefinitionTest(unittest.TestCase):
 
+    Metadata = DocstyleDefinition.Metadata
+    dummy_metadata = Metadata(":param ", ":", ":return:")
+
     def test_fail_instantation(self):
         with self.assertRaises(ValueError):
-            DocstyleDefinition("PYTHON", "doxyGEN", (("##", "#"),))
+            DocstyleDefinition("PYTHON", "doxyGEN",
+                               (("##", "#"),), self.dummy_metadata)
 
         with self.assertRaises(ValueError):
             DocstyleDefinition("WEIRD-PY",
                                "schloxygen",
-                               (("##+", "x", "y", "z"),))
+                               (("##+", "x", "y", "z"),),
+                               self.dummy_metadata)
 
         with self.assertRaises(ValueError):
             DocstyleDefinition("PYTHON",
                                "doxygen",
-                               (("##", "", "#"), ('"""', '"""')))
+                               (("##", "", "#"), ('"""', '"""')),
+                               self.dummy_metadata)
+
+        with self.assertRaises(TypeError):
+            DocstyleDefinition(123, ["doxygen"], (('"""', '"""')),
+                               self.dummy_metadata)
 
         with self.assertRaises(TypeError):
-            DocstyleDefinition(123, ["doxygen"], (('"""', '"""')))
+            DocstyleDefinition("language", ["doxygen"], (('"""', '"""')),
+                               "metdata")
 
     def test_properties(self):
-        uut = DocstyleDefinition("C", "doxygen", (("/**", "*", "*/"),))
+        uut = DocstyleDefinition("C", "doxygen",
+                                 (("/**", "*", "*/"),), self.dummy_metadata)
 
         self.assertEqual(uut.language, "c")
         self.assertEqual(uut.docstyle, "doxygen")
         self.assertEqual(uut.markers, (("/**", "*", "*/"),))
+        self.assertEqual(uut.metadata, self.dummy_metadata)
 
-        uut = DocstyleDefinition("PYTHON", "doxyGEN", [("##", "", "#")])
+        uut = DocstyleDefinition("PYTHON", "doxyGEN",
+                                 [("##", "", "#")], self.dummy_metadata)
 
         self.assertEqual(uut.language, "python")
         self.assertEqual(uut.docstyle, "doxygen")
         self.assertEqual(uut.markers, (("##", "", "#"),))
+        self.assertEqual(uut.metadata, self.dummy_metadata)
 
         uut = DocstyleDefinition("I2C",
                                  "my-custom-tool",
-                                 (["~~", "/~", "/~"], (">!", ">>", ">>")))
+                                 (["~~", "/~", "/~"], (">!", ">>", ">>")),
+                                 self.dummy_metadata)
 
         self.assertEqual(uut.language, "i2c")
         self.assertEqual(uut.docstyle, "my-custom-tool")
         self.assertEqual(uut.markers, (("~~", "/~", "/~"), (">!", ">>", ">>")))
+        self.assertEqual(uut.metadata, self.dummy_metadata)
 
-        uut = DocstyleDefinition("Cpp", "doxygen", ("~~", "/~", "/~"))
+        uut = DocstyleDefinition("Cpp", "doxygen",
+                                 ("~~", "/~", "/~"), self.dummy_metadata)
 
         self.assertEqual(uut.language, "cpp")
         self.assertEqual(uut.docstyle, "doxygen")
         self.assertEqual(uut.markers, (("~~", "/~", "/~"),))
+        self.assertEqual(uut.metadata, self.dummy_metadata)
 
     def test_load(self):
         # Test unregistered docstyle.
@@ -73,7 +92,10 @@ def test_load(self):
         self.assertEqual(result.docstyle, "default")
         self.assertEqual(result.markers, (('"""', '', '"""'),))
 
+        self.assertEqual(result.metadata, self.dummy_metadata)
+
     def test_load_external_coalang(self):
+        empty_metadata = self.Metadata('', '', '')
         with TemporaryDirectory() as directory:
             coalang_file = os.path.join(directory, "custom.coalang")
             with open(coalang_file, "w") as file:
@@ -84,3 +106,4 @@ def test_load_external_coalang(self):
             self.assertEqual(result.language, "cool")
             self.assertEqual(result.docstyle, "custom")
             self.assertEqual(result.markers, (('@@', '@@', '@@'),))
+            self.assertEqual(result.metadata, empty_metadata)