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

4 files changed, 15 insertions, 9 deletions

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"/>