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

8 files changed, 72 insertions, 41 deletions

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)}