Expand inline references to D-Bus interfaces, methods, signals and properties

This is just like gtk-doc

org.project.Bar.HelloWorld()

Signed-off-by: David Zeuthen <davidz@redhat.com>

3 files changed, 52 insertions, 16 deletions

diff --git a/src/codegen_docbook.py b/src/codegen_docbook.py
index 8b25b6d..517b363 100644
--- a/src/codegen_docbook.py
+++ b/src/codegen_docbook.py
@@ -38,7 +38,7 @@ class DocbookCodeGenerator:
 
         if in_synopsis:
             self.out.write('<link linkend="gdbus-method-%s.%s">%s</link>%*s ('
-                           %(i.name, m.name, m.name, max_method_len - len(m.name), ''))
+                           %(utils.dots_to_hyphens(i.name), m.name, m.name, max_method_len - len(m.name), ''))
         else:
             self.out.write('%s%*s ('
                            %(m.name, max_method_len - len(m.name), ''))
@@ -74,7 +74,7 @@ class DocbookCodeGenerator:
 
         if in_synopsis:
             self.out.write('<link linkend="gdbus-signal-%s.%s">%s</link>%*s ('
-                           %(i.name, s.name, s.name, max_signal_len - len(s.name), ''))
+                           %(utils.dots_to_hyphens(i.name), s.name, s.name, max_signal_len - len(s.name), ''))
         else:
             self.out.write('%s%*s ('
                            %(s.name, max_signal_len - len(s.name), ''))
@@ -103,7 +103,7 @@ class DocbookCodeGenerator:
 
         if in_synopsis:
             self.out.write('<link linkend="gdbus-property-%s.%s">%s</link>%*s'
-                           %(i.name, p.name, p.name, max_property_len - len(p.name), ''))
+                           %(utils.dots_to_hyphens(i.name), p.name, p.name, max_property_len - len(p.name), ''))
         else:
             self.out.write('%s%*s'
                            %(p.name, max_property_len - len(p.name), ''))
@@ -144,55 +144,83 @@ class DocbookCodeGenerator:
         self.out.write('  </refsect1>\n'%())
 
     def print_method(self, i, m):
-        self.out.write('<refsect2 role="method" id="gdbus-method-%s.%s">\n'%(i.name, m.name))
+        self.out.write('<refsect2 role="method" id="gdbus-method-%s.%s">\n'%(utils.dots_to_hyphens(i.name), m.name))
         self.out.write('  <title>The %s() method</title>\n'%(m.name))
         self.out.write('  <indexterm zone="gdbus-method-%s.%s"><primary sortas="%s.%s">%s.%s()</primary></indexterm>\n'%(i.name, m.name, i.name_without_prefix, m.name, i.name, m.name))
         self.out.write('<programlisting>\n')
         self.print_method_prototype(i, m, in_synopsis=False)
         self.out.write('</programlisting>\n')
-        self.out.write('<para>%s</para>\n'%(m.doc_string))
+        self.out.write('<para>%s</para>\n'%(self.expand(m.doc_string)))
         self.out.write('<variablelist role="params">\n')
         for a in m.in_args:
             self.out.write('<varlistentry>\n'%())
             self.out.write('  <term><literal>IN %s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name))
-            self.out.write('  <listitem><para>%s</para></listitem>\n'%(a.doc_string))
+            self.out.write('  <listitem><para>%s</para></listitem>\n'%(self.expand(a.doc_string)))
             self.out.write('</varlistentry>\n'%())
         for a in m.out_args:
             self.out.write('<varlistentry>\n'%())
             self.out.write('  <term><literal>OUT %s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name))
-            self.out.write('  <listitem><para>%s</para></listitem>\n'%(a.doc_string))
+            self.out.write('  <listitem><para>%s</para></listitem>\n'%(self.expand(a.doc_string)))
             self.out.write('</varlistentry>\n'%())
         self.out.write('</variablelist>\n')
         self.out.write('</refsect2>\n')
 
     def print_signal(self, i, s):
-        self.out.write('<refsect2 role="signal" id="gdbus-signal-%s.%s">\n'%(i.name, s.name))
+        self.out.write('<refsect2 role="signal" id="gdbus-signal-%s.%s">\n'%(utils.dots_to_hyphens(i.name), s.name))
         self.out.write('  <title>The "%s" signal</title>\n'%(s.name))
         self.out.write('  <indexterm zone="gdbus-signal-%s.%s"><primary sortas="%s::%s">%s::%s</primary></indexterm>\n'%(i.name, s.name, i.name_without_prefix, s.name, i.name, s.name))
         self.out.write('<programlisting>\n')
         self.print_signal_prototype(i, s, in_synopsis=False)
         self.out.write('</programlisting>\n')
-        self.out.write('<para>%s</para>\n'%(s.doc_string))
+        self.out.write('<para>%s</para>\n'%(self.expand(s.doc_string)))
         self.out.write('<variablelist role="params">\n')
         for a in s.args:
             self.out.write('<varlistentry>\n'%())
             self.out.write('  <term><literal>%s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name))
-            self.out.write('  <listitem><para>%s</para></listitem>\n'%(a.doc_string))
+            self.out.write('  <listitem><para>%s</para></listitem>\n'%(self.expand(a.doc_string)))
             self.out.write('</varlistentry>\n'%())
         self.out.write('</variablelist>\n')
         self.out.write('</refsect2>\n')
 
     def print_property(self, i, p):
-        self.out.write('<refsect2 role="property" id="gdbus-property-%s.%s">\n'%(i.name, p.name))
+        self.out.write('<refsect2 role="property" id="gdbus-property-%s.%s">\n'%(utils.dots_to_hyphens(i.name), p.name))
         self.out.write('  <title>The "%s" property</title>\n'%(p.name))
         self.out.write('  <indexterm zone="gdbus-property-%s.%s"><primary sortas="%s:%s">%s:%s</primary></indexterm>\n'%(i.name, p.name, i.name_without_prefix, p.name, i.name, p.name))
         self.out.write('<programlisting>\n')
         self.print_property_prototype(i, p, in_synopsis=False)
         self.out.write('</programlisting>\n')
-        self.out.write('<para>%s</para>\n'%(p.doc_string))
+        self.out.write('<para>%s</para>\n'%(self.expand(p.doc_string)))
         self.out.write('</refsect2>\n')
 
+    def expand(self, s):
+        for key in self.expand_member_dict:
+            s = s.replace(key, self.expand_member_dict[key])
+        for key in self.expand_iface_dict:
+            s = s.replace(key, self.expand_iface_dict[key])
+        return s
+
+    def generate_expand_dicts(self):
+        self.expand_member_dict = {}
+        self.expand_iface_dict = {}
+        for i in self.ifaces:
+            key = '#%s'%(i.name)
+            value = '<link linkend="gdbus-interface-%s.top_of_page">%s</link>'%(utils.dots_to_hyphens(i.name), i.name)
+            self.expand_iface_dict[key] = value
+            for m in i.methods:
+                key = '%s.%s()'%(i.name, m.name)
+                value = '<link linkend="gdbus-method-%s.%s">%s.%s()</link>'%(utils.dots_to_hyphens(i.name), m.name, i.name, m.name)
+                self.expand_member_dict[key] = value
+            for s in i.signals:
+                key = '#%s::%s'%(i.name, s.name)
+                value = '<link linkend="gdbus-signal-%s.%s">%s::%s</link>'%(utils.dots_to_hyphens(i.name), s.name, i.name, s.name)
+                self.expand_member_dict[key] = value
+            for p in i.properties:
+                key = '#%s:%s'%(i.name, p.name)
+                value = '<link linkend="gdbus-property-%s.%s">%s:%s</link>'%(utils.dots_to_hyphens(i.name), p.name, i.name, p.name)
+                self.expand_member_dict[key] = value
+
     def generate(self):
+        self.generate_expand_dicts()
         for i in self.ifaces:
             self.out = file('%s-%s.xml'%(self.docbook, i.name), 'w')
             self.out.write(''%())
@@ -202,8 +230,8 @@ class DocbookCodeGenerator:
             self.out.write(']>\n'%())
             self.out.write('<refentry id="gdbus-%s">\n'%(i.name))
             self.out.write('  <refmeta>'%())
-            self.out.write('    <refentrytitle role="top_of_page" id="gdbus-%s.top_of_page">%s</refentrytitle>\n'%(i.name, i.name))
-            self.out.write('  <indexterm zone="gdbus-%s.top_of_page"><primary sortas="%s">%s</primary></indexterm>\n'%(i.name, i.name_without_prefix, i.name))
+            self.out.write('    <refentrytitle role="top_of_page" id="gdbus-interface-%s.top_of_page">%s</refentrytitle>\n'%(utils.dots_to_hyphens(i.name), i.name))
+            self.out.write('  <indexterm zone="gdbus-interface-%s.top_of_page"><primary sortas="%s">%s</primary></indexterm>\n'%(utils.dots_to_hyphens(i.name), i.name_without_prefix, i.name))
             self.out.write('  </refmeta>'%())
 
             self.out.write('  <refnamediv>'%())
@@ -218,9 +246,9 @@ class DocbookCodeGenerator:
             if len(i.properties) > 0:
                 self.print_synopsis_properties(i)
 
-            self.out.write('<refsect1 role="desc" id="gdbus-interface-%s">\n'%(i.name))
+            self.out.write('<refsect1 role="desc" id="gdbus-interface-%s">\n'%(utils.dots_to_hyphens(i.name)))
             self.out.write('  <title role="desc.title">Description</title>\n'%())
-            self.out.write('  <para>%s</para>\n'%(i.doc_string))
+            self.out.write('  <para>%s</para>\n'%(self.expand(i.doc_string)))
             self.out.write('</refsect1>\n'%())
 
             if len(i.methods) > 0:
diff --git a/src/org.project.xml b/src/org.project.xml
index 11dc0e1..fdd5a1f 100644
--- a/src/org.project.xml
+++ b/src/org.project.xml
@@ -252,6 +252,11 @@
       The docs for the actual method.
 
       Multi-paragraph.
+
+      Test of inline links: The #org.project.Bar D-Bus interface,
+      org.project.Bar.HelloWorld() method, the
+      #org.project.Bar::TestSignal, the
+      #org.project.InlineDocs:Property3 property.
     -->
     <method name="FooMethod">
       <arg name="greeting" direction="in" type="s"/>
diff --git a/src/utils.py b/src/utils.py
index d58ef7f..4966077 100644
--- a/src/utils.py
+++ b/src/utils.py
@@ -14,6 +14,9 @@ def strip_dots(s):
                 ret += c
     return ret
 
+def dots_to_hyphens(s):
+    return s.replace('.', '-')
+
 def camel_case_to_uscore(s):
     ret = ''
     insert_uscore = False