Properly process documentation references.

stone/target/tsd_client.py

@@ -11,6 +11,7 @@
 from stone.target.tsd_helpers import (
     fmt_error_type,
     fmt_func,
+    fmt_tag,
     fmt_type,
     fmt_union,
 )
@@ -117,8 +118,6 @@ def _generate_route(self, route_schema, namespace, route):
 
     def _docf(self, tag, val):
         """
-        Callback used as the handler argument to process_docs(). This converts
-        Stone doc references to JSDoc-friendly annotations.
+        Callback to process documentation references.
         """
-        # TODO(kelkabany): We're currently just dropping all doc ref tags.
-        return val
+        return fmt_tag(None, tag, val)

stone/target/tsd_helpers.py

@@ -108,3 +108,27 @@ def fmt_func(name):
 
 def fmt_var(name):
     return fmt_camel(name)
+
+def fmt_tag(cur_namespace, tag, val):
+    """
+    Processes a documentation reference.
+    """
+    if tag == 'type':
+        fq_val = val
+        if '.' not in val and cur_namespace != None:
+            fq_val = cur_namespace.name + '.' + fq_val
+        return fq_val
+    elif tag == 'route':
+        return fmt_func(val) + "()"
+    elif tag == 'link':
+        anchor, link = val.rsplit(' ', 1)
+        # There's no way to have links in TSDoc, so simply use JSDoc's formatting.
+        # It's entirely possible some editors support this.
+        return '[%s]{@link %s}' % (anchor, link)
+    elif tag == 'val':
+        # Value types seem to match JavaScript (true, false, null)
+        return val
+    elif tag == 'field':
+        return val
+    else:
+        raise RuntimeError('Unknown doc ref tag %r' % tag)

stone/target/tsd_types.py

@@ -20,7 +20,9 @@
     fmt_pascal,
 )
 from stone.target.tsd_helpers import (
+    fmt_func,
     fmt_polymorphic_type_reference,
+    fmt_tag,
     fmt_type,
     fmt_type_name,
     fmt_union,
@@ -103,6 +105,8 @@ class TSDTypesGenerator(CodeGenerator):
 
     preserve_aliases = True
 
+    cur_namespace = None
+
     def generate(self, api):
         spaces_per_indent = self.args.spaces_per_indent
         indent_level = self.args.indent_level
@@ -140,12 +144,15 @@ def _generate_types(self, api, spaces_per_indent, indent_level, extra_args):
             self.emit()
 
             for namespace in api.namespaces.values():
+                self.cur_namespace = namespace
                 # Count aliases as data types too!
                 data_types = namespace.data_types + namespace.aliases
                 # Skip namespaces that do not contain types.
                 if len(data_types) == 0:
                     continue;
 
+                if namespace.doc:
+                    self._emit_tsdoc_header(namespace.doc)
                 self.emit_wrapped_text('namespace %s {' % namespace.name)
 
                 with self.indent(dent = spaces_per_indent):
@@ -219,7 +226,7 @@ def exit(m):
 
     def _emit_tsdoc_header(self, docstring):
         self.emit('/**')
-        self.emit_wrapped_text(docstring, prefix = ' * ')
+        self.emit_wrapped_text(self.process_doc(docstring, self._docf), prefix = ' * ')
         self.emit(' */')
 
     def _generate_type(self, data_type, indent_spaces, extra_args):
@@ -365,8 +372,6 @@ def _generate_union_type(self, union_type, indent_spaces):
 
     def _docf(self, tag, val):
         """
-        Callback used as the handler argument to process_docs(). This converts
-        Stone doc references to JSDoc-friendly annotations.
+        Callback to process documentation references.
         """
-        # TODO(kelkabany): We're currently just dropping all doc ref tags.
-        return val
+        return fmt_tag(self.cur_namespace, tag, val)