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

8 files changed, 18 insertions, 10 deletions

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.