docwriter: Define a new formatter method for getting params

This will let us gracefully skip over parameters that aren't exposed
by specific language bindings.

It also fixes a bug in the C/Python documentation where we weren't
iterating over the right parameters.

8 files changed, 41 insertions, 29 deletions

diff --git a/giscanner/doctemplates/C/function.tmpl b/giscanner/doctemplates/C/function.tmpl
index e76eda31..c551bc2e 100644
--- a/giscanner/doctemplates/C/function.tmpl
+++ b/giscanner/doctemplates/C/function.tmpl
@@ -10,7 +10,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 node.all_parameters:
+% for arg in formatter.get_parameters(node):
 % if arg.type.ctype == '<varargs>':
       <api:varargs/>
 % else:
@@ -25,10 +25,10 @@
 <%block name="synopsis">
 <synopsis><code mime="text/x-csrc">
 ${node.retval.type.ctype} ${formatter.format_function_name(node)} (\
-% if not node.all_parameters:
+% if not formatter.get_parameters(node):
 void\
 % else:
-% for ix, arg in enumerate(node.all_parameters):
+% for ix, arg in enumerate(formatter.get_parameters(node)):
 % if ix != 0:
 ${' ' * (len(formatter.format_type(node.retval.type)) + len(formatter.format_function_name(node)) + 3)}\
 % endif
@@ -37,7 +37,7 @@ ${' ' * (len(formatter.format_type(node.retval.type)) + len(formatter.format_fun
 % else:
 ${formatter.format_type(arg.type) | x} ${arg.argname}\
 % endif
-% if ix != len(node.all_parameters) - 1:
+% if ix != len(formatter.get_parameters(node)) - 1:
 ,
 % endif
 % endfor
@@ -46,9 +46,9 @@ ${formatter.format_type(arg.type) | x} ${arg.argname}\
 </code></synopsis>
 </%block>
 <%block name="details">
-% if node.all_parameters or node.retval:
+% if formatter.get_parameters(node) or node.retval:
 <dl>
-% for arg in node.parameters:
+% for arg in formatter.get_parameters(node):
 <dt><p>${arg.argname} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
diff --git a/giscanner/doctemplates/Gjs/function.tmpl b/giscanner/doctemplates/Gjs/function.tmpl
index 2039405d..db2c8ae3 100644
--- a/giscanner/doctemplates/Gjs/function.tmpl
+++ b/giscanner/doctemplates/Gjs/function.tmpl
@@ -10,7 +10,7 @@
         <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
       </api:returns>
       <api:name>${node.symbol}</api:name>
-% for arg in node.parameters:
+% for arg in formatter.get_parameters(node):
 % if arg.type.ctype == '<varargs>':
       <api:varargs/>
 % else:
@@ -26,16 +26,16 @@
 <synopsis><code mime="text/x-gjs">
 function \
 ${node.name}(\
-${', '.join('%s:%s' % (arg.argname, formatter.format_type(arg.type)) for arg in node.parameters)}\
+${', '.join('%s:%s' % (arg.argname, formatter.format_type(arg.type)) for arg in formatter.get_parameters(node))}\
 ):${formatter.format_type(node.retval.type)} {
     // Gjs wrapper for ${node.symbol}()
 }
 </code></synopsis>
 </%block>
 <%block name="details">
-% if node.parameters or node.retval:
+% if formatter.get_parameters(node) or node.retval:
 <dl>
-% for arg in node.parameters:
+% for arg in formatter.get_parameters(node):
 <dt><p>${arg.argname} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
diff --git a/giscanner/doctemplates/Gjs/signal.tmpl b/giscanner/doctemplates/Gjs/signal.tmpl
index f2eb5868..83264804 100644
--- a/giscanner/doctemplates/Gjs/signal.tmpl
+++ b/giscanner/doctemplates/Gjs/signal.tmpl
@@ -6,7 +6,7 @@
 <%block name="synopsis">
 <synopsis><code mime="text/x-python">
 function callback(${formatter.to_underscores(node.parent.name).lower()}, \
-% for arg in node.parameters:
+% for arg in formatter.get_parameters(node):
 ${arg.argname}:${formatter.format_type(arg.type)}, \
 % endfor
 user_param1, ...):${formatter.format_type(node.retval.type)};
@@ -16,7 +16,7 @@ user_param1, ...):${formatter.format_type(node.retval.type)};
 <dl>
 <dt><p>${formatter.to_underscores(node.parent.name).lower()} :</p></dt>
 <dd><p>instance of ${namespace.name}.${node.parent.name} that is emitting the signal</p></dd>
-% for arg in node.parameters:
+% for arg in formatter.get_parameters(node):
 <dt><p>${arg.argname} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
diff --git a/giscanner/doctemplates/Gjs/vfunc.tmpl b/giscanner/doctemplates/Gjs/vfunc.tmpl
index 2e5d8c94..1d132c78 100644
--- a/giscanner/doctemplates/Gjs/vfunc.tmpl
+++ b/giscanner/doctemplates/Gjs/vfunc.tmpl
@@ -2,15 +2,15 @@
 <%block name="synopsis">
 <synopsis><code mime="text/x-gjs">
 function vfunc_${node.name}(\
-${', '.join('%s:%s' % (arg.argname, formatter.format_type(arg.type)) for arg in node.parameters)}\
+${', '.join('%s:%s' % (arg.argname, formatter.format_type(arg.type)) for arg in formatter.get_parameters(node))}\
 ):${formatter.format_type(node.retval.type)} {
 }
 </code></synopsis>
 </%block>
 <%block name="details">
-% if node.parameters or node.retval:
+% if formatter.get_parameters(node) or node.retval:
 <dl>
-% for arg in node.parameters:
+% for arg in formatter.get_parameters(node):
 <dt><p>${arg.argname} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
diff --git a/giscanner/doctemplates/Python/function.tmpl b/giscanner/doctemplates/Python/function.tmpl
index 23fde041..356619c3 100644
--- a/giscanner/doctemplates/Python/function.tmpl
+++ b/giscanner/doctemplates/Python/function.tmpl
@@ -10,7 +10,7 @@
         <api:type>${formatter.format_type(node.retval.type) | x}</api:type>
       </api:returns>
       <api:name>${node.symbol}</api:name>
-% for arg in node.all_parameters:
+% for arg in formatter.get_parameters(node):
 % if arg.type.ctype == '<varargs>':
       <api:varargs/>
 % else:
@@ -24,23 +24,23 @@
 </%block>
 <%block name="synopsis">
 <synopsis><code mime="text/x-python">
-% if node.all_parameters:
+% if formatter.get_parameters(node):
 @accepts(\
-${', '.join((formatter.format_type(arg.type) for arg in node.all_parameters))}\
+${', '.join((formatter.format_type(arg.type) for arg in formatter.get_parameters(node)))}\
 )
 % endif
 @returns(${formatter.format_type(node.retval.type) | x})
 def \
 ${node.name}(\
-${', '.join((formatter.format_parameter_name(node, arg) for arg in node.all_parameters))}\
+${', '.join((formatter.format_parameter_name(node, arg) for arg in formatter.get_parameters(node)))}\
 ):
     # Python wrapper for ${node.symbol}()
 </code></synopsis>
 </%block>
 <%block name="details">
-% if node.all_parameters or node.retval:
+% if formatter.get_parameters(node) or node.retval:
 <dl>
-% for ix, arg in enumerate(node.all_parameters):
+% for ix, arg in enumerate(formatter.get_parameters(node)):
 <dt><p>${formatter.format_parameter_name(node, arg)} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
diff --git a/giscanner/doctemplates/Python/signal.tmpl b/giscanner/doctemplates/Python/signal.tmpl
index abb3a3ae..0df13f64 100644
--- a/giscanner/doctemplates/Python/signal.tmpl
+++ b/giscanner/doctemplates/Python/signal.tmpl
@@ -6,7 +6,7 @@
 <%block name="synopsis">
 <synopsis><code mime="text/x-python">
 def callback(${formatter.to_underscores(node.parent.name).lower()}, \
-% for arg in node.parameters:
+% for arg in formatter.get_parameters(node):
 ${arg.argname}, \
 % endfor
 user_param1, ...)
@@ -16,7 +16,7 @@ user_param1, ...)
 <dl>
 <dt><p>${formatter.to_underscores(node.parent.name).lower()} :</p></dt>
 <dd><p>instance of ${namespace.name}.${node.parent.name} that is emitting the signal</p></dd>
-% for arg in node.parameters:
+% for arg in formatter.get_parameters(node):
 <dt><p>${arg.argname} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
diff --git a/giscanner/doctemplates/Python/vfunc.tmpl b/giscanner/doctemplates/Python/vfunc.tmpl
index 6f7e6920..c4716a5e 100644
--- a/giscanner/doctemplates/Python/vfunc.tmpl
+++ b/giscanner/doctemplates/Python/vfunc.tmpl
@@ -1,22 +1,22 @@
 <%inherit file="/base.tmpl"/>
 <%block name="synopsis">
 <synopsis><code mime="text/x-python">
-% if node.parameters:
+% if formatter.get_parameters(node):
 @accepts(\
-${', '.join((formatter.format_type(arg.type) for arg in node.parameters))}\
+${', '.join((formatter.format_type(arg.type) for arg in formatter.get_parameters(node)))}\
 )
 % endif
 @returns(${formatter.format_type(node.retval.type) | x})
 def \
-do_${node.name}(self, \
-${', '.join((arg.argname for arg in node.parameters))}\
+do_${node.name}(\
+${', '.join((arg.argname for arg in formatter.get_parameters(node)))}\
 ):
 </code></synopsis>
 </%block>
 <%block name="details">
-% if node.parameters or node.retval:
+% if formatter.get_parameters(node) or node.retval:
 <dl>
-% for arg in node.parameters:
+% for arg in formatter.get_parameters(node):
 <dt><p>${arg.argname} :</p></dt>
 <dd>${formatter.format(node, arg.doc)}</dd>
 % endfor
diff --git a/giscanner/docwriter.py b/giscanner/docwriter.py
index 2b9cb0fc..be4d74ff 100644
--- a/giscanner/docwriter.py
+++ b/giscanner/docwriter.py
@@ -289,6 +289,9 @@ class DocFormatter(object):
 
         return dispatch[kind](node, match, props)
 
+    def get_parameters(self, node):
+        raise NotImplementedError
+
     def format_inline(self, node, para):
         tokens = self._scanner.scan(para)
         words = [self._process_token(node, tok) for tok in tokens]
@@ -374,6 +377,9 @@ class DocFormatterC(DocFormatter):
         else:
             return func.name
 
+    def get_parameters(self, node):
+        return node.all_parameters
+
 class DocFormatterPython(DocFormatter):
     language = "Python"
     mime_type = "text/python"
@@ -450,6 +456,9 @@ class DocFormatterPython(DocFormatter):
         else:
             return func.name
 
+    def get_parameters(self, node):
+        return node.all_parameters
+
 class DocFormatterGjs(DocFormatter):
     language = "Gjs"
     mime_type = "text/x-gjs"
@@ -520,6 +529,9 @@ class DocFormatterGjs(DocFormatter):
         else:
             return func.name
 
+    def get_parameters(self, node):
+        return node.parameters
+
 LANGUAGES = {
     "c": DocFormatterC,
     "python": DocFormatterPython,