Permalink
Browse files

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.
  • Loading branch information...
SanketDG committed Jul 12, 2016
1 parent 7de9aed commit 31b041044ce139ef017fc6f373c6a1f52ab8fe8c
@@ -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)
@@ -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
@@ -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 = \#\#, \#, \#
@@ -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)

0 comments on commit 31b0410

Please sign in to comment.