From 75d25b7f47542aa003c92ce576b6e82bae66aec9 Mon Sep 17 00:00:00 2001
From: Giovanni Campagna <gcampagna@src.gnome.org>
Date: Wed, 19 Feb 2014 16:19:53 +0100
Subject: doctool: improve Gjs documentation

- Add documentation for structures, fields, constants and
  callbacks
- Improve the synopsis for interfaces to have prerequisites
  and known implementations
- Respect gjs constraints for field writability
- Format in and out parameters for callables according to GJS
  conventions
- Format property names according to the GJS API
- Show boxed constructors according to how they can be used
  in the gjs API

https://bugzilla.gnome.org/show_bug.cgi?id=724735
---
 giscanner/doctemplates/C/callback.tmpl       |  4 ++++
 giscanner/doctemplates/C/field.tmpl          |  1 +
 giscanner/doctemplates/C/function.tmpl       | 17 ++++++++--------
 giscanner/doctemplates/C/interface.tmpl      |  2 ++
 giscanner/doctemplates/Gjs/callback.tmpl     | 27 ++++++++++++++++++++++++++
 giscanner/doctemplates/Gjs/class.tmpl        | 11 +++++++----
 giscanner/doctemplates/Gjs/field.tmpl        |  9 +++++++++
 giscanner/doctemplates/Gjs/function.tmpl     | 23 +++++++++++-----------
 giscanner/doctemplates/Gjs/interface.tmpl    | 17 ++++++++++++++++
 giscanner/doctemplates/Gjs/property.tmpl     |  7 +++----
 giscanner/doctemplates/Gjs/signal.tmpl       | 19 +++++++++---------
 giscanner/doctemplates/Gjs/vfunc.tmpl        | 14 +++++++-------
 giscanner/doctemplates/Python/callback.tmpl  | 27 ++++++++++++++++++++++++++
 giscanner/doctemplates/Python/class.tmpl     |  9 +++++----
 giscanner/doctemplates/Python/field.tmpl     |  1 +
 giscanner/doctemplates/Python/function.tmpl  | 22 ++++++++-------------
 giscanner/doctemplates/Python/interface.tmpl | 16 +++++++++++++++
 giscanner/doctemplates/Python/property.tmpl  |  5 ++---
 giscanner/doctemplates/Python/signal.tmpl    | 13 ++++++-------
 giscanner/doctemplates/Python/vfunc.tmpl     | 20 +++++++------------
 giscanner/doctemplates/base.tmpl             | 29 ++++++++++------------------
 giscanner/doctemplates/class.tmpl            | 27 +++++++++++++++++++++++---
 giscanner/doctemplates/namespace.tmpl        | 11 ++++-------
 23 files changed, 216 insertions(+), 115 deletions(-)
 create mode 100644 giscanner/doctemplates/C/callback.tmpl
 create mode 100644 giscanner/doctemplates/C/field.tmpl
 create mode 100644 giscanner/doctemplates/C/interface.tmpl
 create mode 100644 giscanner/doctemplates/Gjs/callback.tmpl
 create mode 100644 giscanner/doctemplates/Gjs/field.tmpl
 create mode 100644 giscanner/doctemplates/Gjs/interface.tmpl
 create mode 100644 giscanner/doctemplates/Python/callback.tmpl
 create mode 100644 giscanner/doctemplates/Python/field.tmpl
 create mode 100644 giscanner/doctemplates/Python/interface.tmpl

(limited to 'giscanner/doctemplates')

diff --git a/giscanner/doctemplates/C/callback.tmpl b/giscanner/doctemplates/C/callback.tmpl
new file mode 100644
index 00000000..f285ff68
--- /dev/null
+++ b/giscanner/doctemplates/C/callback.tmpl
@@ -0,0 +1,4 @@
+<%inherit file="./function.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+  </%block>
diff --git a/giscanner/doctemplates/C/field.tmpl b/giscanner/doctemplates/C/field.tmpl
new file mode 100644
index 00000000..b66ae926
--- /dev/null
+++ b/giscanner/doctemplates/C/field.tmpl
@@ -0,0 +1 @@
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/C/function.tmpl b/giscanner/doctemplates/C/function.tmpl
index 8d669438..3f9e6275 100644
--- a/giscanner/doctemplates/C/function.tmpl
+++ b/giscanner/doctemplates/C/function.tmpl
@@ -6,7 +6,7 @@
         <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
       </api:returns>
       <api:name>${formatter.format_function_name(node)}</api:name>
-% for arg in formatter.get_parameters(node):
+% for arg in formatter.get_in_parameters(node):
 % if arg.type.ctype == '<varargs>':
       <api:varargs/>
 % else:
@@ -19,12 +19,12 @@
     </api:function>
 </%block>
 <%block name="synopsis">
-<synopsis><code mime="text/x-csrc">
+  <synopsis><code mime="text/x-csrc">
 ${node.retval.type.ctype} ${formatter.format_function_name(node)} (\
-% if not formatter.get_parameters(node):
+% if not formatter.get_in_parameters(node):
 void\
 % else:
-% for ix, arg in enumerate(formatter.get_parameters(node)):
+% for ix, arg in enumerate(formatter.get_in_parameters(node)):
 % if ix != 0:
 ${' ' * (len(formatter.format_type(node.retval.type)) + len(formatter.format_function_name(node)) + 3)}\
 % endif
@@ -33,18 +33,17 @@ ${' ' * (len(formatter.format_type(node.retval.type)) + len(formatter.format_fun
 % else:
 ${formatter.format_type(arg.type) | x} ${arg.argname}\
 % endif
-% if ix != len(formatter.get_parameters(node)) - 1:
+% if ix != len(formatter.get_in_parameters(node)) - 1:
 ,
 % endif
 % endfor
 % endif
 );
-</code></synopsis>
-</%block>
+  </code></synopsis></%block>
 <%block name="details">
-% if formatter.get_parameters(node) or node.retval:
+% if formatter.get_in_parameters(node) or node.retval:
 <terms>
-% for arg in formatter.get_parameters(node):
+% for arg in formatter.get_in_parameters(node):
 <item>
 <title><code>${arg.argname}</code></title>
 ${formatter.format(node, arg.doc)}
diff --git a/giscanner/doctemplates/C/interface.tmpl b/giscanner/doctemplates/C/interface.tmpl
new file mode 100644
index 00000000..3f18b021
--- /dev/null
+++ b/giscanner/doctemplates/C/interface.tmpl
@@ -0,0 +1,2 @@
+<%! page_type="guide" %>\
+<%inherit file="/class.tmpl"/>
diff --git a/giscanner/doctemplates/Gjs/callback.tmpl b/giscanner/doctemplates/Gjs/callback.tmpl
new file mode 100644
index 00000000..d7b97794
--- /dev/null
+++ b/giscanner/doctemplates/Gjs/callback.tmpl
@@ -0,0 +1,27 @@
+<%inherit file="/base.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-gjs">
+function on${node.name}(\
+${', '.join('%s: %s' % (arg.argname, formatter.format_type(arg.type, True)) for arg in formatter.get_in_parameters(node))}\
+): ${formatter.format_out_parameters(node)} {
+}
+  </code></synopsis></%block>
+<%block name="details">
+% if formatter.has_any_parameters(node):
+<terms>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% for arg in formatter.get_out_parameters(node):
+<item>
+<title><code>${(arg.argname + ' (out)') if arg.direction == 'inout' else arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+</terms>
+% endif
+</%block>
+
diff --git a/giscanner/doctemplates/Gjs/class.tmpl b/giscanner/doctemplates/Gjs/class.tmpl
index 887c646b..d8433704 100644
--- a/giscanner/doctemplates/Gjs/class.tmpl
+++ b/giscanner/doctemplates/Gjs/class.tmpl
@@ -3,16 +3,19 @@
   <synopsis><code>
 const ${namespace.name} = imports.gi.${namespace.name};
 
-let ${formatter.to_underscores(node.name).lower()} = new ${namespace.name}.${node.name}(\
+let ${formatter.to_lower_camel_case(node.name)} = new ${namespace.name}.${node.name}(\
+% if isinstance(node, (ast.Class, ast.Interface)):
 % if len(node.properties) > 0:
 {
 % for ix, property_ in enumerate(node.properties):
-% if property_.construct or property_.construct_only or property_.writable:
+% if (property_.construct or property_.construct_only) and property_.writable:
     <link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>: value,
 % endif
 % endfor
 }\
 % endif
+% else:
+${formatter.format_gboxed_constructor(node)}\
+% endif
 );
-  </code></synopsis>
-</%block>
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/Gjs/field.tmpl b/giscanner/doctemplates/Gjs/field.tmpl
new file mode 100644
index 00000000..dda82469
--- /dev/null
+++ b/giscanner/doctemplates/Gjs/field.tmpl
@@ -0,0 +1,9 @@
+<%inherit file="/base.tmpl"/>
+<%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+    <title type="link" role="topic">${node.name}</title>
+</%block>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-gjs">
+${node.parent.name}.${formatter.to_underscores(node)}: ${formatter.format_type(node.type, True)} (${formatter.format_property_flags(node)})
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/Gjs/function.tmpl b/giscanner/doctemplates/Gjs/function.tmpl
index e0fd9612..012978ac 100644
--- a/giscanner/doctemplates/Gjs/function.tmpl
+++ b/giscanner/doctemplates/Gjs/function.tmpl
@@ -6,7 +6,7 @@
         <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
       </api:returns>
       <api:name>${node.symbol}</api:name>
-% for arg in formatter.get_parameters(node):
+% for arg in formatter.get_in_parameters(node):
 % if arg.type.ctype == '<varargs>':
       <api:varargs/>
 % else:
@@ -19,30 +19,29 @@
     </api:function>
 </%block>
 <%block name="synopsis">
-<synopsis><code mime="text/x-gjs">
+  <synopsis><code mime="text/x-gjs">
 function \
 ${node.name}(\
-${', '.join('%s:%s' % (arg.argname, formatter.format_type(arg.type)) for arg in formatter.get_parameters(node))}\
-):${formatter.format_type(node.retval.type)} {
+${', '.join('%s: %s' % (arg.argname, formatter.format_type(arg.type, True)) for arg in formatter.get_in_parameters(node))}\
+): ${formatter.format_out_parameters(node)} {
     // Gjs wrapper for ${node.symbol}()
 }
-</code></synopsis>
-</%block>
+  </code></synopsis></%block>
 <%block name="details">
-% if formatter.get_parameters(node) or node.retval:
+% if formatter.has_any_parameters(node):
 <terms>
-% for arg in formatter.get_parameters(node):
+% for arg in formatter.get_in_parameters(node):
 <item>
 <title><code>${arg.argname}</code></title>
 ${formatter.format(node, arg.doc)}
 </item>
 % endfor
-% if node.retval and node.retval.type.ctype != 'void':
+% for arg in formatter.get_out_parameters(node):
 <item>
-<title><code>Returns</code></title>
-${formatter.format(node, node.retval.doc)}
+<title><code>${(arg.argname + ' (out)') if arg.direction == 'inout' else arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
 </item>
-% endif
+% endfor
 </terms>
 % endif
 </%block>
diff --git a/giscanner/doctemplates/Gjs/interface.tmpl b/giscanner/doctemplates/Gjs/interface.tmpl
new file mode 100644
index 00000000..2f01f20f
--- /dev/null
+++ b/giscanner/doctemplates/Gjs/interface.tmpl
@@ -0,0 +1,17 @@
+<%inherit file="/class.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code>
+const ${namespace.name} = imports.gi.${namespace.name};
+
+let ${formatter.to_underscores(node).lower()} = new ${namespace.name}.${node.name}(\
+% if len(node.properties) > 0:
+{
+% for ix, property_ in enumerate(node.properties):
+% if (property_.construct or property_.construct_only) and property_.writable:
+    <link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>: value,
+% endif
+% endfor
+}\
+% endif
+);
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/Gjs/property.tmpl b/giscanner/doctemplates/Gjs/property.tmpl
index 3316a00c..dda82469 100644
--- a/giscanner/doctemplates/Gjs/property.tmpl
+++ b/giscanner/doctemplates/Gjs/property.tmpl
@@ -4,7 +4,6 @@
     <title type="link" role="topic">${node.name}</title>
 </%block>
 <%block name="synopsis">
-<synopsis><code mime="text/x-python">
-"${node.name}"             ${formatter.format_type(node.type)}                : ${formatter.format_property_flags(node)}
-</code></synopsis>
-</%block>
+  <synopsis><code mime="text/x-gjs">
+${node.parent.name}.${formatter.to_underscores(node)}: ${formatter.format_type(node.type, True)} (${formatter.format_property_flags(node)})
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/Gjs/signal.tmpl b/giscanner/doctemplates/Gjs/signal.tmpl
index 084d9743..7c508162 100644
--- a/giscanner/doctemplates/Gjs/signal.tmpl
+++ b/giscanner/doctemplates/Gjs/signal.tmpl
@@ -4,21 +4,22 @@
     <title type="link" role="topic">${node.name}</title>
 </%block>
 <%block name="synopsis">
-<synopsis><code mime="text/x-python">
-function callback(${formatter.to_underscores(node.parent.name).lower()}, \
-% for arg in formatter.get_parameters(node):
-${arg.argname}:${formatter.format_type(arg.type)}, \
+  <synopsis><code mime="text/x-gjs">
+connect('${node.name}', function (${formatter.to_lower_camel_case(node.parent.name)}, \
+% for arg in formatter.get_in_parameters(node):
+% if arg.type.target_fundamental != 'none':
+${arg.argname}: ${formatter.format_type(arg.type, True)}, \
+% endif
 % endfor
-):${formatter.format_type(node.retval.type)};
-</code></synopsis>
-</%block>
+): ${formatter.format_type(node.retval.type, True)});
+  </code></synopsis></%block>
 <%block name="details">
 <terms>
 <item>
-<title><code>${formatter.to_underscores(node.parent.name).lower()}</code></title>
+<title><code>${formatter.to_lower_camel_case(node.parent.name)}</code></title>
 <p>instance of ${formatter.format_xref(node.parent)} that is emitting the signal</p>
 </item>
-% for arg in formatter.get_parameters(node):
+% for arg in formatter.get_in_parameters(node):
 <item>
 <title><code>${arg.argname}</code></title>
 ${formatter.format(node, arg.doc)}
diff --git a/giscanner/doctemplates/Gjs/vfunc.tmpl b/giscanner/doctemplates/Gjs/vfunc.tmpl
index 1cbe511c..2bd1127d 100644
--- a/giscanner/doctemplates/Gjs/vfunc.tmpl
+++ b/giscanner/doctemplates/Gjs/vfunc.tmpl
@@ -1,16 +1,15 @@
 <%inherit file="/base.tmpl"/>
 <%block name="synopsis">
-<synopsis><code mime="text/x-gjs">
+  <synopsis><code mime="text/x-gjs">
 function vfunc_${node.name}(\
-${', '.join('%s:%s' % (arg.argname, formatter.format_type(arg.type)) for arg in formatter.get_parameters(node))}\
-):${formatter.format_type(node.retval.type)} {
+${', '.join('%s: %s' % (arg.argname, formatter.format_type(arg.type, True)) for arg in formatter.get_in_parameters(node))}\
+): ${formatter.format_out_parameters(node)} {
 }
-</code></synopsis>
-</%block>
+  </code></synopsis></%block>
 <%block name="details">
-% if formatter.get_parameters(node) or node.retval:
+% if formatter.get_in_parameters(node) or node.retval:
 <terms>
-% for arg in formatter.get_parameters(node):
+% for arg in formatter.get_in_parameters(node):
 <item>
 <title><code>${arg.argname}</code></title>
 ${formatter.format(node, arg.doc)}
@@ -25,3 +24,4 @@ ${formatter.format(node, node.retval.doc)}
 </terms>
 % endif
 </%block>
+
diff --git a/giscanner/doctemplates/Python/callback.tmpl b/giscanner/doctemplates/Python/callback.tmpl
new file mode 100644
index 00000000..4fcbfe3b
--- /dev/null
+++ b/giscanner/doctemplates/Python/callback.tmpl
@@ -0,0 +1,27 @@
+<%inherit file="/base.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code mime="text/x-python">
+% if formatter.get_in_parameters(node):
+@accepts(${', '.join((formatter.format_type(arg.type) for arg in formatter.get_in_parameters(node)))})
+% endif
+@returns(${formatter.format_type(node.retval.type) | x})
+def on_${node.name}(${', '.join((arg.argname for arg in formatter.get_in_parameters(node)))}):
+  </code></synopsis></%block>
+<%block name="details">
+% if formatter.get_in_parameters(node) or node.retval:
+<terms>
+% for arg in formatter.get_in_parameters(node):
+<item>
+<title><code>${arg.argname}</code></title>
+${formatter.format(node, arg.doc)}
+</item>
+% endfor
+% if node.retval and node.retval.type.ctype != 'void':
+<item>
+<title><code>Returns</code></title>
+${formatter.format(node, node.retval.doc)}
+</item>
+% endif
+</terms>
+% endif
+</%block>
diff --git a/giscanner/doctemplates/Python/class.tmpl b/giscanner/doctemplates/Python/class.tmpl
index 435b31a5..51d25a91 100644
--- a/giscanner/doctemplates/Python/class.tmpl
+++ b/giscanner/doctemplates/Python/class.tmpl
@@ -3,7 +3,8 @@
   <synopsis><code>
 from gi.repository import ${namespace.name}
 
-${formatter.to_underscores(node.name).lower()} = ${namespace.name}.${node.name}(\
+${formatter.to_underscores(node).lower()} = ${namespace.name}.${node.name}(\
+% if isinstance(node, (ast.Class, ast.Interface)):
 % for ix, property_ in enumerate(node.properties):
 % if property_.construct or property_.construct_only or property_.writable:
 <link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>=value\
@@ -12,6 +13,6 @@ ${formatter.to_underscores(node.name).lower()} = ${namespace.name}.${node.name}(
 % endif
 % endif
 % endfor
-)\
-  </code></synopsis>
-</%block>
+% endif
+)
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/Python/field.tmpl b/giscanner/doctemplates/Python/field.tmpl
new file mode 100644
index 00000000..b66ae926
--- /dev/null
+++ b/giscanner/doctemplates/Python/field.tmpl
@@ -0,0 +1 @@
+<%inherit file="/base.tmpl"/>
diff --git a/giscanner/doctemplates/Python/function.tmpl b/giscanner/doctemplates/Python/function.tmpl
index 072a1185..7ad1ac04 100644
--- a/giscanner/doctemplates/Python/function.tmpl
+++ b/giscanner/doctemplates/Python/function.tmpl
@@ -6,7 +6,7 @@
         <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
       </api:returns>
       <api:name>${node.symbol}</api:name>
-% for arg in formatter.get_parameters(node):
+% for arg in formatter.get_in_parameters(node):
 % if arg.type.ctype == '<varargs>':
       <api:varargs/>
 % else:
@@ -19,24 +19,18 @@
     </api:function>
 </%block>
 <%block name="synopsis">
-<synopsis><code mime="text/x-python">
-% if formatter.get_parameters(node):
-@accepts(\
-${', '.join((formatter.format_type(arg.type) for arg in formatter.get_parameters(node)))}\
-)
+  <synopsis><code mime="text/x-python">
+% if formatter.get_in_parameters(node):
+@accepts(${', '.join((formatter.format_type(arg.type) for arg in formatter.get_in_parameters(node)))})
 % endif
 @returns(${formatter.format_type(node.retval.type) | x})
-def \
-${node.name}(\
-${', '.join((formatter.format_parameter_name(node, arg) for arg in formatter.get_parameters(node)))}\
-):
+def ${node.name}(${', '.join((formatter.format_parameter_name(node, arg) for arg in formatter.get_in_parameters(node)))}):
     # Python wrapper for ${node.symbol}()
-</code></synopsis>
-</%block>
+  </code></synopsis></%block>
 <%block name="details">
-% if formatter.get_parameters(node) or node.retval:
+% if formatter.get_in_parameters(node) or node.retval:
 <terms>
-% for ix, arg in enumerate(formatter.get_parameters(node)):
+% for ix, arg in enumerate(formatter.get_in_parameters(node)):
 <item>
 <title><code>${formatter.format_parameter_name(node, arg)}</code></title>
 ${formatter.format(node, arg.doc)}
diff --git a/giscanner/doctemplates/Python/interface.tmpl b/giscanner/doctemplates/Python/interface.tmpl
new file mode 100644
index 00000000..b3596a8d
--- /dev/null
+++ b/giscanner/doctemplates/Python/interface.tmpl
@@ -0,0 +1,16 @@
+<%inherit file="/class.tmpl"/>
+<%block name="synopsis">
+  <synopsis><code>
+from gi.repository import ${namespace.name}
+
+${formatter.to_underscores(node).lower()} = ${namespace.name}.${node.name}(\
+% for ix, property_ in enumerate(node.properties):
+% if property_.construct or property_.construct_only or property_.writable:
+<link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>=value\
+% if ix != len(node.properties) - 1:
+, \
+% endif
+% endif
+% endfor
+)\
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/Python/property.tmpl b/giscanner/doctemplates/Python/property.tmpl
index 3316a00c..c93d59b7 100644
--- a/giscanner/doctemplates/Python/property.tmpl
+++ b/giscanner/doctemplates/Python/property.tmpl
@@ -4,7 +4,6 @@
     <title type="link" role="topic">${node.name}</title>
 </%block>
 <%block name="synopsis">
-<synopsis><code mime="text/x-python">
+  <synopsis><code mime="text/x-python">
 "${node.name}"             ${formatter.format_type(node.type)}                : ${formatter.format_property_flags(node)}
-</code></synopsis>
-</%block>
+  </code></synopsis></%block>
diff --git a/giscanner/doctemplates/Python/signal.tmpl b/giscanner/doctemplates/Python/signal.tmpl
index dc931107..c61b7229 100644
--- a/giscanner/doctemplates/Python/signal.tmpl
+++ b/giscanner/doctemplates/Python/signal.tmpl
@@ -4,21 +4,20 @@
     <title type="link" role="topic">${node.name}</title>
 </%block>
 <%block name="synopsis">
-<synopsis><code mime="text/x-python">
-def callback(${formatter.to_underscores(node.parent.name).lower()}, \
-% for arg in formatter.get_parameters(node):
+  <synopsis><code mime="text/x-python">
+def callback(${formatter.to_underscores(node.parent).lower()}, \
+% for arg in formatter.get_in_parameters(node):
 ${arg.argname}, \
 % endfor
 user_param1, ...)
-</code></synopsis>
-</%block>
+  </code></synopsis></%block>
 <%block name="details">
 <terms>
 <item>
-<title><code>${formatter.to_underscores(node.parent.name).lower()}</code></title>
+<title><code>${formatter.to_underscores(node.parent).lower()}</code></title>
 <p>instance of ${formatter.format_xref(node.parent)} that is emitting the signal</p>
 </item>
-% for arg in formatter.get_parameters(node):
+% for arg in formatter.get_in_parameters(node):
 <item>
 <title><code>${arg.argname}</code></title>
 ${formatter.format(node, arg.doc)}
diff --git a/giscanner/doctemplates/Python/vfunc.tmpl b/giscanner/doctemplates/Python/vfunc.tmpl
index 98a30932..2c532e70 100644
--- a/giscanner/doctemplates/Python/vfunc.tmpl
+++ b/giscanner/doctemplates/Python/vfunc.tmpl
@@ -1,22 +1,16 @@
 <%inherit file="/base.tmpl"/>
 <%block name="synopsis">
-<synopsis><code mime="text/x-python">
-% if formatter.get_parameters(node):
-@accepts(\
-${', '.join((formatter.format_type(arg.type) for arg in formatter.get_parameters(node)))}\
-)
+  <synopsis><code mime="text/x-python">
+% if formatter.get_in_parameters(node):
+@accepts(${', '.join((formatter.format_type(arg.type) for arg in formatter.get_in_parameters(node)))})
 % endif
 @returns(${formatter.format_type(node.retval.type) | x})
-def \
-do_${node.name}(\
-${', '.join((arg.argname for arg in formatter.get_parameters(node)))}\
-):
-</code></synopsis>
-</%block>
+def do_${node.name}(${', '.join((arg.argname for arg in formatter.get_in_parameters(node)))}):
+  </code></synopsis></%block>
 <%block name="details">
-% if formatter.get_parameters(node) or node.retval:
+% if formatter.get_in_parameters(node) or node.retval:
 <terms>
-% for arg in formatter.get_parameters(node):
+% for arg in formatter.get_in_parameters(node):
 <item>
 <title><code>${arg.argname}</code></title>
 ${formatter.format(node, arg.doc)}
diff --git a/giscanner/doctemplates/base.tmpl b/giscanner/doctemplates/base.tmpl
index 78980773..7a1d8db2 100644
--- a/giscanner/doctemplates/base.tmpl
+++ b/giscanner/doctemplates/base.tmpl
@@ -6,24 +6,15 @@
       xmlns="http://projectmallard.org/1.0/"
       xmlns:api="http://projectmallard.org/experimental/api/"
       xmlns:ui="http://projectmallard.org/1.0/ui/">
-  <info>
-    <%block name="info">
-      ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
-    </%block>
+  <info><%block name="info">
+    ${formatter.format_xref(node.parent, type="guide", group=page_kind)}
+</%block>\
   </info>
-  <title><%block name="title">${formatter.format_page_name(node)}</%block></title>
-  <%block name="synopsis">
-  </%block>
-  <%block name="doc">
-    ${formatter.format(node, node.doc)}
-  </%block>
-  <%block name="since_version">
-    % if node.version:
-    <p>Since ${node.version}</p>
-    % endif
-  </%block>
-  <%block name="details">
-  </%block>
-  <%block name="links">
-  </%block>
+  <title><%block name="title">${formatter.format_page_name(node)}</%block></title><%block name="synopsis"></%block><%block name="doc">
+${formatter.format(node, node.doc)}
+</%block><%block name="since_version">\
+% if node.version:
+  <p>Since ${node.version}</p>\
+% endif
+</%block><%block name="details"></%block><%block name="links"></%block>
 </page>
diff --git a/giscanner/doctemplates/class.tmpl b/giscanner/doctemplates/class.tmpl
index 7f8b6869..86333866 100644
--- a/giscanner/doctemplates/class.tmpl
+++ b/giscanner/doctemplates/class.tmpl
@@ -1,6 +1,7 @@
 <%! page_type="guide" %>\
 <%inherit file="/base.tmpl"/>
 <%block name="details">
+% if isinstance(node, ast.Class):
   <synopsis>
     <title>Hierarchy</title>
     <tree>
@@ -13,8 +14,23 @@
 % endfor
     </tree>
   </synopsis>
+% elif isinstance(node, ast.Interface):
+  <synopsis>
+    <title>Prerequisites</title>
+    <p>${node.name} requires ${formatter.format_prerequisites(node)}</p>
+  </synopsis>
+  <synopsis>
+    <title>Known Implementations</title>
+    <p>${formatter.format_known_implementations(node)}</p>
+  </synopsis>
+% endif
 </%block>
-<%block name="links">
+<%block name="links">\
+  <links type="topic" ui:expanded="true"
+         api:type="function" api:mime="${formatter.mime_type}"
+         groups="constructor" style="linklist">
+    <title>Constructors</title>
+  </links>
   <links type="topic" ui:expanded="true"
          api:type="function" api:mime="${formatter.mime_type}"
          groups="method" style="linklist">
@@ -23,8 +39,9 @@
   <links type="topic" ui:expanded="true"
          api:type="function" api:mime="${formatter.mime_type}"
          groups="function" style="linklist">
-    <title>Functions</title>
+    <title>Static Functions</title>
   </links>
+% if isinstance(node, (ast.Class, ast.Interface)):
   <links type="topic" ui:expanded="true" groups="property" style="linklist">
     <title>Properties</title>
   </links>
@@ -34,7 +51,11 @@
   <links type="topic" ui:expanded="true" groups="vfunc" style="linklist">
     <title>Virtual functions</title>
   </links>
+% endif
+  <links type="topic" ui:expanded="true" groups="field" style="linklist">
+    <title>Fields</title>
+  </links>
   <links type="topic" ui:expanded="true" groups="#first #default #last" style="linklist">
     <title>Other</title>
-  </links>
+  </links>\
 </%block>
diff --git a/giscanner/doctemplates/namespace.tmpl b/giscanner/doctemplates/namespace.tmpl
index bb58bb16..d4edcec0 100644
--- a/giscanner/doctemplates/namespace.tmpl
+++ b/giscanner/doctemplates/namespace.tmpl
@@ -1,11 +1,9 @@
 <%! page_type="guide" %>\
 <%inherit file="/base.tmpl"/>
-<%block name="doc">
-</%block>
-<%block name="info">
-</%block>
+<%block name="doc"></%block>
+<%block name="info"></%block>
 <%block name="links">
-  <links type="topic" ui:expanded="true" groups="class" style="linklist">
+  <links type="topic" ui:expanded="true" groups="class interface" style="linklist">
     <title>Classes</title>
   </links>
   <links type="topic" ui:expanded="true" groups="function" style="linklist">
@@ -15,5 +13,4 @@
     <title>Other</title>
   </links>
 </%block>
-<%block name="since_version">
-</%block>
+<%block name="since_version"></%block>
-- 
cgit v1.2.1