mallardwriter: Add support for parameters

Support the inline @my_parameter syntax, and translate it to
<code>my_parameter</code>, as Mallard doesn't have anything
more fancy than that. For Python, where we omit the first parameter
of methods like that automatically, force to "self".

9 files changed, 47 insertions, 10 deletions

diff --git a/giscanner/mallardwriter.py b/giscanner/mallardwriter.py
index 8c228ce8..09701817 100644
--- a/giscanner/mallardwriter.py
+++ b/giscanner/mallardwriter.py
@@ -150,6 +150,7 @@ class DocstringScanner(TemplatedScanner):
             ('signal', r'#<<type_name:alpha>>::(<<signal_name:alpha_dash>>)'),
             ('type_name', r'#(<<type_name:alpha>>)'),
             ('fundamental', r'%(<<fundamental:alpha>>)'),
+            ('parameter', r'@<<param_name:alpha>>'),
             ('function_call', r'<<symbol_name:alpha>>\(\)'),
         ]
 
@@ -239,6 +240,14 @@ class MallardFormatter(object):
     def _process_fundamental(self, node, match, props):
         return self.fundamentals.get(props['fundamental'], match)
 
+    def _process_parameter(self, node, match, props):
+        try:
+            parameter = node.get_parameter(props['param_name'])
+        except (AttributeError, ValueError), e:
+            return match
+
+        return '<code>%s</code>' % (self.format_parameter_name(node, parameter), )
+
     def _process_function_call(self, node, match, props):
         func = self._resolve_symbol(props['symbol_name'])
         if func is None:
@@ -255,6 +264,7 @@ class MallardFormatter(object):
             'signal': self._process_signal,
             'type_name': self._process_type_name,
             'fundamental': self._process_fundamental,
+            'parameter': self._process_parameter,
             'function_call': self._process_function_call,
         }
 
@@ -265,6 +275,9 @@ class MallardFormatter(object):
         words = [self._process_token(node, tok) for tok in tokens]
         return ''.join(words)
 
+    def format_parameter_name(self, node, parameter):
+        return parameter.argname
+
     def format_function_name(self, func):
         raise NotImplementedError
 
@@ -344,6 +357,22 @@ class MallardFormatterPython(MallardFormatter):
         "NULL": "None",
     }
 
+    def is_method(self, node):
+        if getattr(node, "is_method", False):
+            return True
+
+        if isinstance(node, (ast.VFunction)):
+            return True
+
+        return False
+
+    def format_parameter_name(self, node, parameter):
+        # Force "self" for the first parameter of a method
+        if self.is_method(node) and parameter is node.parameters[0]:
+            return "self"
+        else:
+            return parameter.argname
+
     def format_type(self, type_):
         if isinstance(type_, ast.Array):
             return '[' + self.format_type(type_.element_type) + ']'
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 5f27f96f..0312ab98 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
@@ -66,7 +66,7 @@ created with <link xref="DocExamples.Obj.new">doc_examples_obj_new</link>.</p><p
 </tr>
 <tr>
 <td><p>pointer_arg :</p></td>
-<td><p>If not NULL, do a thing.</p></td>
+<td><p>If not NULL, do a thing. Pass <code>first_arg</code> if you want to sometimes. You can also pass <code>second_arg</code>, or even <code>boolean_arg</code>.</p></td>
 </tr>
 <tr>
 <td><p>string :</p></td>
diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page
index ae7791e9..f5f2145b 100644
--- a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page
@@ -33,7 +33,7 @@ and a return value.</p>
 </tr>
 <tr>
 <td><p>Returns :</p></td>
-<td><p>TRUE if @out_arg is valid, FALSE otherwise</p></td>
+<td><p>TRUE if <code>out_arg</code> is valid, FALSE otherwise</p></td>
 </tr>
 </table>
 </page>
diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page
index 98958b22..436d825f 100644
--- a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page
@@ -35,7 +35,7 @@ void doc_examples_callback_function (DocExamplesCallback callback,
 </code></synopsis>
 <p>This is a function that takes a callback. Different languages
 will expose this in different ways (e.g. Python keeps the
-@user_data parameter, while JS doesn't)</p>
+<code>user_data</code> parameter, while JS doesn't)</p>
 
 <table>
 <tr>
@@ -48,7 +48,7 @@ will expose this in different ways (e.g. Python keeps the
 </tr>
 <tr>
 <td><p>destroy_notify :</p></td>
-<td><p>how to get rid of @user_data</p></td>
+<td><p>how to get rid of <code>user_data</code></p></td>
 </tr>
 <tr>
 <td><p>Returns :</p></td>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-signal-example.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-signal-example.page
index d83d2d82..0304b135 100644
--- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-signal-example.page
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-signal-example.page
@@ -10,7 +10,7 @@
   </info>
   <title>DocExamples.Obj::signal-example</title>
 <synopsis><code mime="text/x-python">
-def callback(obj, int_param, float_param, user_param1, ...)
+def callback(obj, int_param, float_param, pointer_param, user_param1, ...)
 </code></synopsis>
 <p>This is an example of how to document a signal.</p>
 
@@ -28,6 +28,10 @@ def callback(obj, int_param, float_param, user_param1, ...)
 <td><p>a parameter of type float</p></td>
 </tr>
 <tr>
+<td><p>pointer_param :</p></td>
+<td><p>A pointer to @obj's thingy -- pass <code>int_param</code> if you really want to.</p></td>
+</tr>
+<tr>
 <td><p>user_param1 :</p></td>
 <td><p>first user parameter (if any) specified with the connect() method</p></td>
 </tr>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.method.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.method.page
index 02f3a002..603fb46c 100644
--- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.method.page
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.method.page
@@ -63,7 +63,7 @@ created with <link xref="DocExamples.Obj.new">Obj.new</link>.</p><p>This should
 </tr>
 <tr>
 <td><p>pointer_arg :</p></td>
-<td><p>If not None, do a thing.</p></td>
+<td><p>If not None, do a thing. Pass <code>self</code> if you want to sometimes. You can also pass <code>second_arg</code>, or even <code>boolean_arg</code>.</p></td>
 </tr>
 <tr>
 <td><p>string :</p></td>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page
index d7990e03..8897c785 100644
--- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page
@@ -35,7 +35,7 @@ and a return value.</p>
 </tr>
 <tr>
 <td><p>Returns :</p></td>
-<td><p>True if @out_arg is valid, False otherwise</p></td>
+<td><p>True if <code>out_arg</code> is valid, False otherwise</p></td>
 </tr>
 </table>
 </page>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page
index ace76458..0b6a15cb 100644
--- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page
@@ -35,7 +35,7 @@ def callback_function(callback, user_data, destroy_notify)
 </code></synopsis>
 <p>This is a function that takes a callback. Different languages
 will expose this in different ways (e.g. Python keeps the
-@user_data parameter, while JS doesn't)</p>
+<code>user_data</code> parameter, while JS doesn't)</p>
 
 <table>
 <tr>
@@ -48,7 +48,7 @@ will expose this in different ways (e.g. Python keeps the
 </tr>
 <tr>
 <td><p>destroy_notify :</p></td>
-<td><p>how to get rid of @user_data</p></td>
+<td><p>how to get rid of <code>user_data</code></p></td>
 </tr>
 </table>
 </page>
diff --git a/tests/doctool/doc-examples-obj.c b/tests/doctool/doc-examples-obj.c
index 992e7151..bf4fcc7e 100644
--- a/tests/doctool/doc-examples-obj.c
+++ b/tests/doctool/doc-examples-obj.c
@@ -56,6 +56,8 @@ doc_examples_obj_class_init (DocExamplesObjClass *klass)
    * @obj:
    * @int_param: a parameter of type int
    * @float_param: a parameter of type float
+   * @pointer_param: A pointer to @obj's thingy --
+   *   pass @int_param if you really want to.
    *
    * This is an example of how to document a signal.
    *
@@ -66,7 +68,7 @@ doc_examples_obj_class_init (DocExamplesObjClass *klass)
       G_SIGNAL_RUN_LAST,
       0, NULL, NULL,
       NULL,
-      G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_UINT);
+      G_TYPE_NONE, 3, G_TYPE_UINT, G_TYPE_UINT, G_TYPE_POINTER);
 
   /**
    * DocExamplesObj:property-example:
@@ -106,6 +108,8 @@ doc_examples_obj_new (void)
  * @second_arg: second argument
  * @boolean_arg: You should always pass %TRUE.
  * @pointer_arg: (allow-none): If not %NULL, do a thing.
+ *   Pass @first_arg if you want to sometimes. You can
+ *   also pass @second_arg, or even @boolean_arg.
  * @string: A %NULL-terminated string.
  *
  * This is an example of how to document a method.