[gobject-introspection] giscanner: write virtual method instance parameter docs to .gir file

[Colin Walters <walters src gnome org>]

commit 001631bf9b9e672154492bf6547c0c7c985ed3e0
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Fri Aug 23 08:48:05 2013 +0200

    giscanner: write virtual method instance parameter docs to .gir file

 giscanner/maintransformer.py                       |    6 ++
 .../Regress.FooObject-read_fn.page                 |    2 +-
 .../Regress.TestObj-matrix.page                    |    2 +-
 .../Regress.FooObject-read_fn.page                 |    2 +-
 .../Regress.TestObj-matrix.page                    |    2 +-
 tests/scanner/Regress-1.0-expected.gir             |    4 +
 tests/scanner/WarnLib-1.0-expected.gir             |   59 ++++++++++++++++++++
 .../annotationparser/gi/syntax_whitespace.xml      |   49 ++++++++++++++++
 tests/scanner/warnlib.c                            |   14 +++++
 tests/scanner/warnlib.h                            |    3 +
 10 files changed, 139 insertions(+), 4 deletions(-)
---
diff --git a/giscanner/maintransformer.py b/giscanner/maintransformer.py
index 92a0773..d0eae90 100644
--- a/giscanner/maintransformer.py
+++ b/giscanner/maintransformer.py
@@ -675,7 +675,13 @@ class MainTransformer(object):
     def _apply_annotations_params(self, parent, params, block):
         declparams = set([])
         if parent.instance_parameter:
+            if block:
+                doc_param = block.params.get(parent.instance_parameter.argname)
+            else:
+                doc_param = None
+            self._apply_annotations_param(parent, parent.instance_parameter, doc_param)
             declparams.add(parent.instance_parameter.argname)
+
         for param in params:
             if block:
                 doc_param = block.params.get(param.argname)
diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.FooObject-read_fn.page 
b/tests/scanner/Regress-1.0-C-expected/Regress.FooObject-read_fn.page
index a316adb..f99f3c0 100644
--- a/tests/scanner/Regress-1.0-C-expected/Regress.FooObject-read_fn.page
+++ b/tests/scanner/Regress-1.0-C-expected/Regress.FooObject-read_fn.page
@@ -27,7 +27,7 @@ void read_fn (RegressFooObject* object,
 <terms>
 <item>
 <title><code>object</code></title>
-
+<p>obj</p>
 </item>
 <item>
 <title><code>offset</code></title>
diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.TestObj-matrix.page 
b/tests/scanner/Regress-1.0-C-expected/Regress.TestObj-matrix.page
index 4c8247b..4320365 100644
--- a/tests/scanner/Regress-1.0-C-expected/Regress.TestObj-matrix.page
+++ b/tests/scanner/Regress-1.0-C-expected/Regress.TestObj-matrix.page
@@ -28,7 +28,7 @@ case.</p>
 <terms>
 <item>
 <title><code>obj</code></title>
-
+<p>A <link xref="Regress.TestObj"/></p>
 </item>
 <item>
 <title><code>somestr</code></title>
diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.FooObject-read_fn.page 
b/tests/scanner/Regress-1.0-Python-expected/Regress.FooObject-read_fn.page
index c2ca1c0..6cf532b 100644
--- a/tests/scanner/Regress-1.0-Python-expected/Regress.FooObject-read_fn.page
+++ b/tests/scanner/Regress-1.0-Python-expected/Regress.FooObject-read_fn.page
@@ -27,7 +27,7 @@ def do_read_fn(object, offset, length):
 <terms>
 <item>
 <title><code>object</code></title>
-
+<p>obj</p>
 </item>
 <item>
 <title><code>offset</code></title>
diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.TestObj-matrix.page 
b/tests/scanner/Regress-1.0-Python-expected/Regress.TestObj-matrix.page
index fe7066a..742e6da 100644
--- a/tests/scanner/Regress-1.0-Python-expected/Regress.TestObj-matrix.page
+++ b/tests/scanner/Regress-1.0-Python-expected/Regress.TestObj-matrix.page
@@ -29,7 +29,7 @@ case.</p>
 <terms>
 <item>
 <title><code>obj</code></title>
-
+<p>A <link xref="Regress.TestObj"/></p>
 </item>
 <item>
 <title><code>somestr</code></title>
diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir
index f9ba48c..7b823a3 100644
--- a/tests/scanner/Regress-1.0-expected.gir
+++ b/tests/scanner/Regress-1.0-expected.gir
@@ -1311,6 +1311,7 @@ uses a C sugar return type.</doc>
         </return-value>
         <parameters>
           <instance-parameter name="object" transfer-ownership="none">
+            <doc xml:space="preserve">obj</doc>
             <type name="FooObject" c:type="RegressFooObject*"/>
           </instance-parameter>
           <parameter name="offset" transfer-ownership="none">
@@ -1572,6 +1573,7 @@ uses a C sugar return type.</doc>
           </return-value>
           <parameters>
             <parameter name="object" transfer-ownership="none">
+              <doc xml:space="preserve">obj</doc>
               <type name="FooObject" c:type="RegressFooObject*"/>
             </parameter>
             <parameter name="offset" transfer-ownership="none">
@@ -2825,6 +2827,7 @@ case.</doc>
         </return-value>
         <parameters>
           <instance-parameter name="obj" transfer-ownership="none">
+            <doc xml:space="preserve">A #RegressTestObj</doc>
             <type name="TestObj" c:type="RegressTestObj*"/>
           </instance-parameter>
           <parameter name="somestr" transfer-ownership="none">
@@ -3514,6 +3517,7 @@ the introspection client langage.</doc>
           </return-value>
           <parameters>
             <parameter name="obj" transfer-ownership="none">
+              <doc xml:space="preserve">A #RegressTestObj</doc>
               <type name="TestObj" c:type="RegressTestObj*"/>
             </parameter>
             <parameter name="somestr" transfer-ownership="none">
diff --git a/tests/scanner/WarnLib-1.0-expected.gir b/tests/scanner/WarnLib-1.0-expected.gir
index 0fc0d84..47e3666 100644
--- a/tests/scanner/WarnLib-1.0-expected.gir
+++ b/tests/scanner/WarnLib-1.0-expected.gir
@@ -19,6 +19,26 @@ and/or use gtk-doc annotations.  -->
                glib:type-name="WarnLibWhatever"
                glib:get-type="warnlib_whatever_get_type"
                glib:type-struct="WhateverIface">
+      <virtual-method name="do_boo" invoker="do_boo">
+        <doc xml:space="preserve">Does boo.</doc>
+        <return-value transfer-ownership="none">
+          <type name="none" c:type="void"/>
+        </return-value>
+        <parameters>
+          <instance-parameter name="self" transfer-ownership="none">
+            <doc xml:space="preserve">a WarnLibWhatever</doc>
+            <type name="Whatever" c:type="WarnLibWhatever*"/>
+          </instance-parameter>
+          <parameter name="x" transfer-ownership="none">
+            <doc xml:space="preserve">x parameter</doc>
+            <type name="gint" c:type="int"/>
+          </parameter>
+          <parameter name="y" transfer-ownership="none">
+            <doc xml:space="preserve">y parameter</doc>
+            <type name="gpointer" c:type="gpointer"/>
+          </parameter>
+        </parameters>
+      </virtual-method>
       <virtual-method name="do_moo" invoker="do_moo">
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
@@ -35,6 +55,24 @@ and/or use gtk-doc annotations.  -->
           </parameter>
         </parameters>
       </virtual-method>
+      <method name="do_boo" c:identifier="warnlib_whatever_do_boo">
+        <doc xml:space="preserve">Does boo.</doc>
+        <return-value transfer-ownership="none">
+          <type name="none" c:type="void"/>
+        </return-value>
+        <parameters>
+          <instance-parameter name="self" transfer-ownership="none">
+            <doc xml:space="preserve">a WarnLibWhatever</doc>
+            <type name="Whatever" c:type="WarnLibWhatever*"/>
+          </instance-parameter>
+          <parameter name="arg1" transfer-ownership="none">
+            <type name="gint" c:type="int"/>
+          </parameter>
+          <parameter name="arg2" transfer-ownership="none">
+            <type name="gpointer" c:type="gpointer"/>
+          </parameter>
+        </parameters>
+      </method>
       <method name="do_moo" c:identifier="warnlib_whatever_do_moo">
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
@@ -76,6 +114,27 @@ and/or use gtk-doc annotations.  -->
           </parameters>
         </callback>
       </field>
+      <field name="do_boo">
+        <callback name="do_boo">
+          <return-value transfer-ownership="none">
+            <type name="none" c:type="void"/>
+          </return-value>
+          <parameters>
+            <parameter name="self" transfer-ownership="none">
+              <doc xml:space="preserve">a WarnLibWhatever</doc>
+              <type name="Whatever" c:type="WarnLibWhatever*"/>
+            </parameter>
+            <parameter name="x" transfer-ownership="none">
+              <doc xml:space="preserve">x parameter</doc>
+              <type name="gint" c:type="int"/>
+            </parameter>
+            <parameter name="y" transfer-ownership="none">
+              <doc xml:space="preserve">y parameter</doc>
+              <type name="gpointer" c:type="gpointer"/>
+            </parameter>
+          </parameters>
+        </callback>
+      </field>
     </record>
     <function name="throw_unpaired"
               c:identifier="warnlib_throw_unpaired"
diff --git a/tests/scanner/annotationparser/gi/syntax_whitespace.xml 
b/tests/scanner/annotationparser/gi/syntax_whitespace.xml
index c7934da..3857ea6 100644
--- a/tests/scanner/annotationparser/gi/syntax_whitespace.xml
+++ b/tests/scanner/annotationparser/gi/syntax_whitespace.xml
@@ -72,4 +72,53 @@ Test overriding via the "Rename To" annotation.</description>
  */</output>
 </test>
 
+<test>
+  <input>/**
+ *atk_text_get_default_attributes:
+ * text: an #AtkText
+ *
+ *Creates ...
+ *
+ *Returns: (transfer full): an ...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>atk_text_get_default_attributes</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>text</name>
+          <description>an #AtkText</description>
+        </parameter>
+      </parameters>
+      <description>Creates ...</description>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <annotations>
+            <annotation>
+              <name>transfer</name>
+              <options>
+                <option>
+                  <name>full</name>
+                </option>
+              </options>
+            </annotation>
+          </annotations>
+          <description>an ...</description>
+        </tag>
+      </tags>
+    </docblock>
+  </parser>
+  <output>/**
+ * atk_text_get_default_attributes:
+ * @text: an #AtkText
+ *
+ * Creates ...
+ *
+ * Returns: (transfer full): an ...
+ */</output>
+</test>
+
 </tests>
diff --git a/tests/scanner/warnlib.c b/tests/scanner/warnlib.c
index 940d2b6..d7c1e2a 100644
--- a/tests/scanner/warnlib.c
+++ b/tests/scanner/warnlib.c
@@ -31,3 +31,17 @@ warnlib_whatever_do_moo (WarnLibWhatever *self, int x, gpointer y)
 {
   WARNLIB_WHATEVER_GET_IFACE(self)->do_moo (self, x, y);
 }
+
+/**
+ * warnlib_whatever_do_boo:
+ * @self: a WarnLibWhatever
+ * @x: x parameter
+ * @y: y parameter
+ *
+ * Does boo.
+ */
+void
+warnlib_whatever_do_boo (WarnLibWhatever *self, int x, gpointer y)
+{
+  WARNLIB_WHATEVER_GET_IFACE(self)->do_boo (self, x, y);
+}
diff --git a/tests/scanner/warnlib.h b/tests/scanner/warnlib.h
index 9e448c0..a4c28b4 100644
--- a/tests/scanner/warnlib.h
+++ b/tests/scanner/warnlib.h
@@ -27,9 +27,12 @@ struct _WarnLibWhateverIface
 
   /* explicitly test un-named parameters */
   void (*do_moo) (WarnLibWhatever *self, int, gpointer);
+
+  void (*do_boo) (WarnLibWhatever *self, int x, gpointer y);
 };
 
 void warnlib_whatever_do_moo (WarnLibWhatever *self, int, gpointer);
+void warnlib_whatever_do_boo (WarnLibWhatever *self, int, gpointer);
 
 GType warnlib_whatever_get_type (void) G_GNUC_CONST;