Added new iteration of structured documentation implementation.

3 files changed, 93 insertions, 22 deletions

diff --git a/qface/helper/doc.py b/qface/helper/doc.py
index 34d97a9..c999227 100644
--- a/qface/helper/doc.py
+++ b/qface/helper/doc.py
@@ -1,10 +1,63 @@
-from collections import OrderedDict
+import re
+
+
+translate = None
+"""
+The translare function used for transalting inline tags. The
+function will be called with tag, value arguments.
+
+Example:
+
+    import qface.doc
+
+    def qdoc_translate(tag, value):
+        return '\\{0}{{{1}}}'.format(tag, value)
+
+    qface.doc.translate = qdoc_translate
+"""
+
+
+class DocObject:
+    """
+    The documentation object passed into the template engine
+    """
+    def __init__(self):
+        self.brief = str()
+        self.description = []
+        self.see = []
+        self.deprecated = False
+
+    def add_tag(self, name, value):
+        attr_type = type(getattr(self, name, None))
+        if type(value) == str:
+            value = self._replace_inline_tags(value)
+        if attr_type is bool:
+            setattr(self, name, bool(value))
+        elif attr_type is str:
+            setattr(self, name, str(value))
+        elif attr_type is list:
+            getattr(self, name).append(value)
+
+    @staticmethod
+    def _translate(name, value):
+        return '{{@{0} {1}}}'.format(name, value)
+
+    @staticmethod
+    def _call_translate(mo):
+        global translate
+        name, value = mo.group(1), mo.group(2)
+        translate = translate if translate else DocObject._translate
+        return translate(name, value)
+
+    @staticmethod
+    def _replace_inline_tags(line):
+        return re.sub(r'{@(\w+)\s+([^}]*)}', DocObject._call_translate, line)
 
 
 def parse_doc(s):
     if not s:
         return
-    o = OrderedDict()
+    doc = DocObject()
     tag = None
     s = s[3:-2]  # remove '/**' and '*/'
     for line in s.splitlines():
@@ -14,23 +67,15 @@ def parse_doc(s):
         elif line[0] == '@':
             line = line[1:]
             res = line.split(maxsplit=1)
+            if len(res) == 0:
+                continue
+            tag = res[0]
             if len(res) == 1:
-                tag = res[0]
-                o[tag] = True
+                doc.add_tag(tag, True)
             elif len(res) == 2:
-                tag, value = res[0], res[1]
-                o[tag] = value
+                value = res[1]
+                doc.add_tag(tag, value)
         elif tag:  # append to previous matched tag
-            if type(o[tag]) != list:
-                o[tag] = [o[tag]]
-            o[tag].append(line)
-    return o
-
-
-def replace_tags(s):
-    pass
+            doc.add_tag(tag, line)
+    return doc
 
-# {% with doc = parse_doc(symbol.commment) %}
-#   \brief {{doc.brief}}
-#   \description {{doc.description}}
-# {% endwith %}
diff --git a/tests/in/org.example.echo.qface b/tests/in/org.example.echo.qface
index f3e7c8b..04a93ce 100644
--- a/tests/in/org.example.echo.qface
+++ b/tests/in/org.example.echo.qface
@@ -4,8 +4,12 @@ module org.example.echo 1.0
 /**
  * @brief the brief
  * @description the description
- * continues
+ * continues {@link http://qt.io}
  * @deprecated
+ * @see org.example.echo.Echo
+ * @see org.example
+ * @see http://qt.io
+ * @anything hello
  */
 interface Echo {
     /**
diff --git a/tests/test_comments.py b/tests/test_comments.py
index d5234a8..707f759 100644
--- a/tests/test_comments.py
+++ b/tests/test_comments.py
@@ -13,6 +13,14 @@ log = logging.getLogger(__name__)
 inputPath = Path('tests/in')
 
 
+def qdoc_translate(name, value):
+    if not value.startswith('http'):
+        value = value.replace('.', '::')
+    return r'\{0}{{{1}}}'.format(name, value)
+
+
+# doc.DocObject.translate = translate
+
 def loadEcho():
     path = inputPath / 'org.example.echo.qface'
     return FileSystem.parse_document(path)
@@ -20,6 +28,7 @@ def loadEcho():
 
 def test_comment():
     system = loadEcho()
+    doc.translate = None
     module = system.lookup('org.example.echo')
     assert module.comment == '/** module */'
     assert module
@@ -27,7 +36,20 @@ def test_comment():
     assert interface
     o = doc.parse_doc(interface.comment)
     # import pdb; pdb.set_trace()
-    assert o['brief'] == 'the brief'
-    assert o['description'] == ['the description', 'continues']
-    assert o['deprecated'] is True
+    assert o.brief == 'the brief'
+    assert o.description == ['the description', 'continues {@link http://qt.io}']
+    assert o.deprecated is True
+    # import pdb; pdb.set_trace()
+    assert o.see == ['org.example.echo.Echo', 'org.example', 'http://qt.io']
+
 
+def test_qdoc_translate():
+    system = loadEcho()
+    module = system.lookup('org.example.echo')
+    assert module.comment == '/** module */'
+    assert module
+    interface = system.lookup('org.example.echo.Echo')
+    assert interface
+    doc.translate = qdoc_translate
+    o = doc.parse_doc(interface.comment)
+    assert o.description == ['the description', 'continues \\link{http://qt.io}']