[Telepathy-commits] [telepathy-spec/master] Initial work on adding docstrings

[Davyd Madeley]

---
 doc/templates/interface.html |    4 ++++
 tools/specparser.py          |   22 ++++++++++++++++++++++
 2 files changed, 26 insertions(+), 0 deletions(-)

diff --git a/doc/templates/interface.html b/doc/templates/interface.html
index 2beda7f..9c7d8db 100644
--- a/doc/templates/interface.html
+++ b/doc/templates/interface.html
@@ -13,6 +13,7 @@
    <a href="#properties">Properties</a>
   </div>
   <div class="main">
+    $interface.get_docstring()
 
    #if $interface.methods
    <div id="methods" class="outset method">
@@ -36,6 +37,7 @@
        $arg.name<br/>
       #end for
      </div>
+     $method.get_docstring()
      #end if
     </div>
     #end for
@@ -57,6 +59,7 @@
       #end for
      </div>
      #end if
+     $signal.get_docstring()
     </div>
     #end for
    </div>
@@ -69,6 +72,7 @@
     <div id="$property.name" class="inset property">
      <span class="permalink">(<a href="$property.get_url()">Permalink</a>)</span>
      <h2>$property.get_short_name()</h2>
+     $property.get_docstring()
     </div>
     #end for
    </div>
diff --git a/tools/specparser.py b/tools/specparser.py
index e69c150..55bceeb 100644
--- a/tools/specparser.py
+++ b/tools/specparser.py
@@ -28,6 +28,15 @@ class base (object):
 
         self.parent = parent
 
+        try:
+            self.docstring = filter (
+                        lambda n: n.nodeType == n.ELEMENT_NODE and \
+                                  n.namespaceURI == XMLNS_TP and \
+                                  n.localName == 'docstring',
+                        dom.childNodes)[0]
+        except IndexError:
+            self.docstring = None
+
     def get_interface (self):
         return self.parent.get_interface ()
 
@@ -37,6 +46,19 @@ class base (object):
     def get_url (self):
         return "%s#%s" % (self.get_interface ().get_url (), self.name)
 
+    def get_docstring (self):
+        """Get the docstring for this node, but do node substitution to
+           rewrite types, interfaces, etc. as links.
+        """
+        if self.docstring is None:
+            return ''
+        else:
+            # make a copy of this code, turn it into a HTML <div> tag
+            node = self.docstring.cloneNode (True)
+            node.tagName = 'div'
+            node.setAttribute ('class', 'docstring')
+            return node.toxml ().encode ('ascii', 'xmlcharrefreplace')
+
     def __repr__ (self):
         return '%s(%s)' % (self.__class__.__name__, self.name)
     
-- 
1.5.6.5