g-ir-doc-tool: Add support for virtual functions

8 files changed, 165 insertions, 0 deletions

diff --git a/giscanner/mallard-C-vfunc.tmpl b/giscanner/mallard-C-vfunc.tmpl
new file mode 100644
index 00000000..5b5bbfb1
--- /dev/null
+++ b/giscanner/mallard-C-vfunc.tmpl
@@ -0,0 +1,35 @@
+<?xml version="1.0"?>
+<page id="${page_id}"
+      type="topic"
+      style="vfunc"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/experimental/ui/">
+  <info>
+    <link type="guide" xref="${namespace.name}.${node.parent.name}" group="vfunc"/>
+  </info>
+  <title>${node.name}</title>
+<synopsis><code mime="text/x-csrc">
+</code></synopsis>
+${formatter.format(node.doc)}
+
+% if node.parameters or node.retval:
+<table>
+% for arg, ix in zip(node.parameters, range(len(node.parameters))):
+<tr>
+<td><p>${arg.argname} :</p></td>
+<td>${formatter.format(arg.doc)}</td>
+</tr>
+% endfor
+% if node.retval:
+<tr>
+<td><p>Returns :</p></td>
+<td>${formatter.format(node.retval.doc)}</td>
+</tr>
+% endif
+</table>
+% endif
+% if node.version:
+<p>Since ${node.version}</p>
+% endif
+</page>
diff --git a/giscanner/mallard-Python-class.tmpl b/giscanner/mallard-Python-class.tmpl
index 62feb9ab..04e5fc72 100644
--- a/giscanner/mallard-Python-class.tmpl
+++ b/giscanner/mallard-Python-class.tmpl
@@ -57,6 +57,9 @@ ${formatter.to_underscores(node.name).lower()} = ${namespace.name}.${node.name}(
   <links type="topic" ui:expanded="yes" groups="signal" style="linklist">
     <title>Signals</title>
   </links>
+  <links type="topic" ui:expanded="yes" groups="vfunc" style="linklist">
+    <title>Virtual functions</title>
+  </links>
   <links type="topic" ui:expanded="yes" groups="#first #default #last" style="linklist">
     <title>Other</title>
   </links>
diff --git a/giscanner/mallard-Python-vfunc.tmpl b/giscanner/mallard-Python-vfunc.tmpl
new file mode 100644
index 00000000..7e95bc85
--- /dev/null
+++ b/giscanner/mallard-Python-vfunc.tmpl
@@ -0,0 +1,56 @@
+<?xml version="1.0"?>
+<page id="${page_id}"
+      type="topic"
+      style="vfunc"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/experimental/ui/">
+  <info>
+    <link type="guide" xref="${namespace.name}.${node.parent.name}" group="vfunc"/>
+    <title type="link" role="topic">${node.name}</title>
+  </info>
+  <title>${namespace.name}.${node.parent.name}.${node.name}</title>
+<synopsis><code mime="text/x-python">
+% if len(node.parameters) != 0:
+@accepts(\
+% for arg, ix in zip(node.parameters, range(len(node.parameters))):
+${formatter.format_type(arg.type) | x}\
+% if ix != len(node.parameters) - 1:
+, \
+%endif
+% endfor
+)
+% endif
+@returns(${formatter.format_type(node.retval.type) | x})
+def \
+do_${node.name}(self, \
+% for arg, ix in zip(node.parameters, range(len(node.parameters))):
+${arg.argname}\
+% if ix != len(node.parameters) - 1:
+, \
+%endif
+% endfor
+):
+</code></synopsis>
+${formatter.format(node.doc)}
+
+% if node.parameters or node.retval:
+<table>
+% for arg, ix in zip(node.parameters, range(len(node.parameters))):
+<tr>
+<td><p>${arg.argname} :</p></td>
+<td>${formatter.format(arg.doc)}</td>
+</tr>
+% endfor
+% if node.retval and node.retval.type.ctype != 'void':
+<tr>
+<td><p>Returns :</p></td>
+<td>${formatter.format(node.retval.doc)}</td>
+</tr>
+% endif
+</table>
+% endif
+% if node.version:
+<p>Since ${node.version}</p>
+% endif
+</page>
diff --git a/giscanner/mallardwriter.py b/giscanner/mallardwriter.py
index 9f11c60b..bb268be7 100644
--- a/giscanner/mallardwriter.py
+++ b/giscanner/mallardwriter.py
@@ -220,6 +220,9 @@ class MallardWriter(object):
         elif isinstance(node, ast.Signal) and node.parent is not None:
             template_name = 'mallard-%s-signal.tmpl' % self._language
             page_id = '%s.%s-%s' % (namespace.name, node.parent.name, node.name)
+        elif isinstance(node, ast.VFunction) and node.parent is not None:
+            template_name = 'mallard-%s-vfunc.tmpl' % self._language
+            page_id = '%s.%s-%s' % (namespace.name, node.parent.name, node.name)
         else:
             template_name = 'mallard-%s-default.tmpl' % self._language
             page_id = '%s.%s' % (namespace.name, node.name)
diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj-vfunc.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj-vfunc.page
new file mode 100644
index 00000000..345d64b9
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj-vfunc.page
@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+<page id="DocExamples.Obj-vfunc"
+      type="topic"
+      style="vfunc"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/experimental/ui/">
+  <info>
+    <link type="guide" xref="DocExamples.Obj" group="vfunc"/>
+  </info>
+  <title>vfunc</title>
+<synopsis><code mime="text/x-csrc">
+</code></synopsis>
+<p>This is an example of how to document a vfunc.</p>
+
+<table>
+<tr>
+<td><p>first_arg :</p></td>
+<td><p>first argument</p></td>
+</tr>
+<tr>
+<td><p>Returns :</p></td>
+<td></td>
+</tr>
+</table>
+<p>Since 0.99</p>
+</page>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-vfunc.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-vfunc.page
new file mode 100644
index 00000000..4e394d2d
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-vfunc.page
@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+<page id="DocExamples.Obj-vfunc"
+      type="topic"
+      style="vfunc"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/experimental/ui/">
+  <info>
+    <link type="guide" xref="DocExamples.Obj" group="vfunc"/>
+    <title type="link" role="topic">vfunc</title>
+  </info>
+  <title>DocExamples.Obj.vfunc</title>
+<synopsis><code mime="text/x-python">
+@accepts(gint)
+@returns(none)
+def do_vfunc(self, first_arg):
+</code></synopsis>
+<p>This is an example of how to document a vfunc.</p>
+
+<table>
+<tr>
+<td><p>first_arg :</p></td>
+<td><p>first argument</p></td>
+</tr>
+</table>
+<p>Since 0.99</p>
+</page>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.page
index cab691e7..071abf1a 100644
--- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.page
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.page
@@ -44,6 +44,9 @@ obj = DocExamples.Obj(<link xref='DocExamples.Obj-property-example'>property_exa
   <links type="topic" ui:expanded="yes" groups="signal" style="linklist">
     <title>Signals</title>
   </links>
+  <links type="topic" ui:expanded="yes" groups="vfunc" style="linklist">
+    <title>Virtual functions</title>
+  </links>
   <links type="topic" ui:expanded="yes" groups="#first #default #last" style="linklist">
     <title>Other</title>
   </links>
diff --git a/tests/doctool/doc-examples-obj.h b/tests/doctool/doc-examples-obj.h
index 46db806d..7bc9e1da 100644
--- a/tests/doctool/doc-examples-obj.h
+++ b/tests/doctool/doc-examples-obj.h
@@ -40,6 +40,17 @@ struct _DocExamplesObj
 struct _DocExamplesObjClass
 {
   GObjectClass parent_class;
+
+  /**
+   * DocExamplesObjClass::vfunc:
+   * @self:
+   * @first_arg: first argument
+   *
+   * This is an example of how to document a vfunc.
+   *
+   * Since: 0.99
+   */
+  void (*vfunc) (DocExamplesObj *self, gint first_arg);
 };
 
 GType doc_examples_obj_get_type (void) G_GNUC_CONST;