[Telepathy-commits] [telepathy-spec/master] Errors and docstrings all around

[Davyd Madeley]

---
 doc/templates/interface.html |   31 +++++++++++++++++++++++--------
 tools/specparser.py          |   35 +++++++++++++++++++++++++++++------
 2 files changed, 52 insertions(+), 14 deletions(-)

diff --git a/doc/templates/interface.html b/doc/templates/interface.html
index af9525d..ee75684 100644
--- a/doc/templates/interface.html
+++ b/doc/templates/interface.html
@@ -25,31 +25,42 @@
      #if $method.in_args
      <div class="indent">
       <h3>Parameters</h3>
+      <ul>
       #for $arg in $method.in_args
-       $arg.short_name &mdash; $arg.dbus_type
-       #if $arg.type: (<a href="$arg.type.get_url()" title="$arg.type.get_title()">$arg.type.short_name</a>)
-       <br/>
+       <li>
+        $arg.short_name &mdash; $arg.dbus_type
+        #if $arg.type: (<a href="$arg.type.get_url()" title="$arg.type.get_title()">$arg.type.short_name</a>)
+       </li>
+       $arg.get_docstring()
       #end for
+      </ul>
      </div>
      #end if
      
      #if $method.out_args
      <div class="indent">
       <h3>Returns</h3>
+      <ul>
       #for $arg in $method.out_args
-       $arg.short_name &mdash; $arg.dbus_type
-       #if $arg.type: (<a href="$arg.type.get_url()" title="$arg.type.get_title()">$arg.type.short_name</a>)
-       <br/>
+       <li>
+        $arg.short_name &mdash; $arg.dbus_type
+        #if $arg.type: (<a href="$arg.type.get_url()" title="$arg.type.get_title()">$arg.type.short_name</a>)
+       </li>
+       $arg.get_docstring()
       #end for
+      </ul>
      </div>
      #end if
      
      #if $method.possible_errors
      <div class="indent">
       <h3>Possible Errors</h3>
+      <ul>
       #for $error in $method.possible_errors
-       $error<br/>
+       <li><a href="$error.get_url()" title="$error.get_title()">$error.short_name</a></li>
+       $error.get_docstring()
       #end for
+      </ul>
      </div>
      #end if
      
@@ -69,11 +80,15 @@
      #if $signal.args
      <div class="indent">
       <h3>Parameters</h3>
+      <ul>
       #for $arg in $signal.args
+       <li>
        $arg.short_name &mdash; $arg.dbus_type
        #if $arg.type: (<a href="$arg.type.get_url()" title="$arg.type.get_title()">$arg.type.short_name</a>)
-       <br/>
+       </li>
+       $arg.get_docstring()
       #end for
+      </ul>
      </div>
      #end if
      $signal.get_docstring()
diff --git a/tools/specparser.py b/tools/specparser.py
index f2f54d6..722f25e 100644
--- a/tools/specparser.py
+++ b/tools/specparser.py
@@ -48,6 +48,9 @@ class base (object):
     def get_spec (self):
         return self.parent.get_spec ()
 
+    def get_root_namespace (self):
+        return self.get_interface ().name
+
     def get_interface (self):
         return self.parent.get_interface ()
 
@@ -75,15 +78,15 @@ class base (object):
 
             # rewrite <tp:member-ref>
             spec = self.get_spec ()
-            interface = self.get_interface ()
+            namespace = self.get_root_namespace ()
             for n in node.getElementsByTagNameNS (XMLNS_TP, 'member-ref'):
                 key = getText (n)
                 try:
-                    o = spec.lookup (key, namespace = interface.name)
+                    o = spec.lookup (key, namespace = namespace)
                 except KeyError:
                     print >> sys.stderr, \
-                        "Key `%s' not known in interface `%s'" % (
-                            key, interface.name)
+                        "Key `%s' not known in namespace `%s'" % (
+                            key, namespace)
                     continue
 
                 n.tagName = 'a'
@@ -120,6 +123,23 @@ class PossibleError (base):
     def __init__ (self, parent, namespace, dom):
         super (PossibleError, self).__init__ (parent, namespace, dom)
 
+    def get_error (self):
+        spec = self.get_spec ()
+        return spec.errors[self.name]
+
+    def get_url (self):
+        self.get_error ().get_url ()
+
+    def get_title (self):
+        self.get_error ().get_title ()
+
+    def get_docstring (self):
+        d = super (PossibleError, self).get_docstring ()
+        if d == '':
+            return self.get_error ().get_docstring ()
+        else:
+            return d
+
 class Method (base):
     def __init__ (self, parent, namespace, dom):
         super (Method, self).__init__ (parent, namespace, dom)
@@ -131,7 +151,7 @@ class Method (base):
         self.in_args = filter (lambda a: a.direction == Arg.DIRECTION_IN, args)
         self.out_args = filter (lambda a: a.direction == Arg.DIRECTION_OUT, args)
 
-        self.possible_errors = build_list (self, PossibleError, self.name,
+        self.possible_errors = build_list (self, PossibleError, None,
                         dom.getElementsByTagNameNS (XMLNS_TP, 'error'))
 
     def get_in_args (self):
@@ -236,6 +256,9 @@ class Interface (base):
 class Error (base):
     def get_url (self):
         return '#FIXME'
+    
+    def get_root_namespace (self):
+        return self.namespace
 
 class DBusType (base):
     """The base class for all D-Bus types referred to in the spec.
@@ -285,7 +308,7 @@ class Spec (object):
 
     def get_spec (self):
         return self
-
+    
     def lookup (self, name, namespace = None):
         key = build_name (namespace, name)
         return self.everything[key]
-- 
1.5.6.5