[gobject-introspection] docwriter: Define a new formatter method for getting params

[Jasper St. Pierre <jstpierre src gnome org>]

commit c9450dc3d7e2f87fa980923594736621f0ecd6ae
Author: Jasper St. Pierre <jstpierre mecheye net>
Date:   Sat Feb 2 11:24:13 2013 -0500

    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.

 giscanner/doctemplates/C/function.tmpl             |   12 ++++++------
 giscanner/doctemplates/Gjs/function.tmpl           |    8 ++++----
 giscanner/doctemplates/Gjs/signal.tmpl             |    4 ++--
 giscanner/doctemplates/Gjs/vfunc.tmpl              |    6 +++---
 giscanner/doctemplates/Python/function.tmpl        |   12 ++++++------
 giscanner/doctemplates/Python/signal.tmpl          |    4 ++--
 giscanner/doctemplates/Python/vfunc.tmpl           |   12 ++++++------
 giscanner/docwriter.py                             |   12 ++++++++++++
 .../DocExamples.Obj-vfunc.page                     |    2 ++
 .../DocExamples.Obj.method.page                    |    2 ++
 .../DocExamples.Obj-vfunc.page                     |    4 +++-
 11 files changed, 48 insertions(+), 30 deletions(-)
---
diff --git a/giscanner/doctemplates/C/function.tmpl b/giscanner/doctemplates/C/function.tmpl
index e76eda3..c551bc2 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 2039405..db2c8ae 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 f2eb586..8326480 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 2e5d8c9..1d132c7 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 23fde04..356619c 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 abb3a3a..0df13f6 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 6f7e692..c4716a5 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 2b9cb0f..be4d74f 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,
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
index 6a71a87..7ff7e56 100644
--- a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj-vfunc.page
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj-vfunc.page
@@ -25,6 +25,8 @@ void vfunc (DocExamplesObj* self,
   
   
 <dl>
+<dt><p>self :</p></dt>
+<dd></dd>
 <dt><p>first_arg :</p></dt>
 <dd><p>first argument</p></dd>
 <dt><p>Returns :</p></dt>
diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.method.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.method.page
index 8dbe8a7..b154b8d 100644
--- a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.method.page
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.method.page
@@ -61,6 +61,8 @@ in as <code>obj</code>.</p><p>This should be a %FALSEALARM.</p>
   
   
 <dl>
+<dt><p>obj :</p></dt>
+<dd><p>A <link xref="DocExamples.Obj"/>.</p></dd>
 <dt><p>first_arg :</p></dt>
 <dd><p>first argument</p></dd>
 <dt><p>second_arg :</p></dt>
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
index a486463..94fe8f6 100644
--- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-vfunc.page
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-vfunc.page
@@ -13,7 +13,7 @@
   <title>DocExamples.Obj::vfunc</title>
   
 <synopsis><code mime="text/x-python">
- accepts(int)
+ accepts(DocExamples.Obj, int)
 @returns(none)
 def do_vfunc(self, first_arg):
 </code></synopsis>
@@ -26,6 +26,8 @@ def do_vfunc(self, first_arg):
   
   
 <dl>
+<dt><p>self :</p></dt>
+<dd></dd>
 <dt><p>first_arg :</p></dt>
 <dd><p>first argument</p></dd>
 </dl>