Clean up annotation parsing, don't try to parse invalid annotations

The old parser tried to parse:
@foo: some text here (other text)
Reject this.  We strictly require another colon at the end to parse
the text in between as (option) (other option).
Futher ensure we only attempt to do option parse if we find something
that matches the strict regexp ([A-Za-z]+).  This could be tightened
further.

TODO: Have a warning for something that looks like an annotation,
but isn't.

https://bugzilla.gnome.org/show_bug.cgi?id=622659

10 files changed, 278 insertions, 180 deletions

diff --git a/gir/Everything-1.0-expected.gir b/gir/Everything-1.0-expected.gir
index 3d3e4e88..36c1153c 100644
--- a/gir/Everything-1.0-expected.gir
+++ b/gir/Everything-1.0-expected.gir
@@ -245,7 +245,9 @@ case.">
           <type name="int" c:type="int"/>
         </return-value>
         <parameters>
-          <parameter name="somestr" transfer-ownership="none">
+          <parameter name="somestr"
+                     transfer-ownership="none"
+                     doc="Meaningless string">
             <type name="utf8" c:type="char*"/>
           </parameter>
         </parameters>
@@ -346,7 +348,9 @@ case.">
           <type name="int" c:type="int"/>
         </return-value>
         <parameters>
-          <parameter name="somestr" transfer-ownership="none">
+          <parameter name="somestr"
+                     transfer-ownership="none"
+                     doc="Meaningless string">
             <type name="utf8" c:type="char*"/>
           </parameter>
         </parameters>
@@ -428,7 +432,9 @@ case.">
             <parameter name="obj" transfer-ownership="none">
               <type name="TestObj" c:type="TestObj*"/>
             </parameter>
-            <parameter name="somestr" transfer-ownership="none">
+            <parameter name="somestr"
+                       transfer-ownership="none"
+                       doc="Meaningless string">
               <type name="utf8" c:type="char*"/>
             </parameter>
           </parameters>
@@ -655,7 +661,8 @@ case.">
     </function>
     <function name="test_array_fixed_size_int_in"
               c:identifier="test_array_fixed_size_int_in">
-      <return-value transfer-ownership="none">
+      <return-value transfer-ownership="none"
+                    doc="the sum of the items in @ints">
         <type name="int" c:type="int"/>
       </return-value>
       <parameters>
@@ -755,7 +762,8 @@ case.">
       </parameters>
     </function>
     <function name="test_array_gtype_in" c:identifier="test_array_gtype_in">
-      <return-value transfer-ownership="full">
+      <return-value transfer-ownership="full"
+                    doc="string representation of provided types">
         <type name="utf8" c:type="char*"/>
       </return-value>
       <parameters>
@@ -780,7 +788,8 @@ case.">
         <parameter name="len"
                    direction="out"
                    caller-allocates="0"
-                   transfer-ownership="full">
+                   transfer-ownership="full"
+                   doc="length of the returned array.">
           <type name="int" c:type="int*"/>
         </parameter>
       </parameters>
@@ -851,7 +860,8 @@ case.">
         <parameter name="len"
                    direction="out"
                    caller-allocates="0"
-                   transfer-ownership="full">
+                   transfer-ownership="full"
+                   doc="length of the returned array.">
           <type name="int" c:type="int*"/>
         </parameter>
       </parameters>
@@ -867,7 +877,7 @@ case.">
             <type name="int"/>
           </array>
         </parameter>
-        <parameter name="len" transfer-ownership="none">
+        <parameter name="len" transfer-ownership="none" doc="length">
           <type name="int" c:type="int"/>
         </parameter>
       </parameters>
@@ -891,7 +901,7 @@ case.">
                    direction="out"
                    caller-allocates="0"
                    transfer-ownership="full"
-                   doc=": length">
+                   doc="length">
           <type name="int" c:type="int*"/>
         </parameter>
       </parameters>
@@ -1077,7 +1087,8 @@ is invoked.">
               doc="Invokes all callbacks installed by #test_callback_destroy_notify(),
 adding up their return values, and removes them, invoking the
 corresponding destroy notfications.">
-      <return-value transfer-ownership="none">
+      <return-value transfer-ownership="none"
+                    doc="Sum of the return values of the invoked callbacks.">
         <type name="int" c:type="int"/>
       </return-value>
     </function>
@@ -1225,7 +1236,8 @@ call and can be released on return.">
       </parameters>
     </function>
     <function name="test_ghash_nested_everything_return"
-              c:identifier="test_ghash_nested_everything_return">
+              c:identifier="test_ghash_nested_everything_return"
+              doc="Specify nested parameterized types directly with the (type ) annotation.">
       <return-value transfer-ownership="full">
         <type name="GLib.HashTable" c:type="GHashTable*">
           <type name="utf8"/>
@@ -1237,7 +1249,8 @@ call and can be released on return.">
       </return-value>
     </function>
     <function name="test_ghash_nested_everything_return2"
-              c:identifier="test_ghash_nested_everything_return2">
+              c:identifier="test_ghash_nested_everything_return2"
+              doc="element-type annotation.">
       <return-value transfer-ownership="full">
         <type name="GLib.HashTable" c:type="GHashTable*">
           <type name="utf8"/>
@@ -2073,7 +2086,8 @@ call and can be released on return.">
     </function>
     <function name="test_utf8_const_return"
               c:identifier="test_utf8_const_return">
-      <return-value transfer-ownership="none">
+      <return-value transfer-ownership="none"
+                    doc="&lt;const char*&gt; UTF-8 string">
         <type name="utf8" c:type="char*"/>
       </return-value>
     </function>
@@ -2103,7 +2117,7 @@ call and can be released on return.">
     </function>
     <function name="test_utf8_nonconst_return"
               c:identifier="test_utf8_nonconst_return">
-      <return-value transfer-ownership="full">
+      <return-value transfer-ownership="full" doc="&lt;char*&gt; UTF-8 string">
         <type name="utf8" c:type="char*"/>
       </return-value>
     </function>
@@ -2187,7 +2201,7 @@ call and can be released on return.">
         <type name="GObject.Value" c:type="GValue*"/>
       </return-value>
       <parameters>
-        <parameter name="i" transfer-ownership="none">
+        <parameter name="i" transfer-ownership="none" doc="an int">
           <type name="int" c:type="int"/>
         </parameter>
       </parameters>
diff --git a/gir/GIMarshallingTests-1.0-expected.gir b/gir/GIMarshallingTests-1.0-expected.gir
index b83dbdf6..4069d1eb 100644
--- a/gir/GIMarshallingTests-1.0-expected.gir
+++ b/gir/GIMarshallingTests-1.0-expected.gir
@@ -1903,7 +1903,7 @@ and/or use gtk-doc annotations.  -->
     </function>
     <function name="gstrv_return"
               c:identifier="g_i_marshalling_tests_gstrv_return">
-      <return-value transfer-ownership="full">
+      <return-value transfer-ownership="full" doc="an array of strings">
         <array c:type="GStrv">
           <type name="utf8"/>
         </array>
diff --git a/gir/everything.c b/gir/everything.c
index 690dc733..2219667f 100644
--- a/gir/everything.c
+++ b/gir/everything.c
@@ -1094,7 +1094,7 @@ static /*const*/ GHashTable *test_table_ghash_const()
 
 /**
  * test_ghash_free:
- * @in: (transfer full) (element-type utf8 utf8)
+ * @in: (transfer full) (element-type utf8 utf8):
  */
 void test_ghash_free (GHashTable *in)
 {
@@ -1840,7 +1840,7 @@ test_obj_do_matrix (TestObj *obj, const char *somestr)
 
 /**
  * test_object_null_in:
- * @obj: (allow-none) A #TestObj
+ * @obj: (allow-none): A #TestObj
  */
 void
 test_object_null_in (TestObj *obj)
@@ -1849,7 +1849,7 @@ test_object_null_in (TestObj *obj)
 
 /**
  * test_object_null_out:
- * @obj: (allow-none) (out) A #TestObj
+ * @obj: (allow-none) (out): A #TestObj
  */
 void
 test_object_null_out (TestObj **obj)
diff --git a/gir/gimarshallingtests.c b/gir/gimarshallingtests.c
index da2fadec..f5f1a8c7 100644
--- a/gir/gimarshallingtests.c
+++ b/gir/gimarshallingtests.c
@@ -35,7 +35,7 @@ g_i_marshalling_tests_boolean_in_false (gboolean bool_)
 
 /**
  * g_i_marshalling_tests_boolean_out_true:
- * bool_: (out):
+ * @bool_: (out):
  */
 void
 g_i_marshalling_tests_boolean_out_true (gboolean *bool_)
@@ -45,7 +45,7 @@ g_i_marshalling_tests_boolean_out_true (gboolean *bool_)
 
 /**
  * g_i_marshalling_tests_boolean_out_false:
- * bool_: (out):
+ * @bool_: (out):
  */
 void
 g_i_marshalling_tests_boolean_out_false (gboolean *bool_)
@@ -55,7 +55,7 @@ g_i_marshalling_tests_boolean_out_false (gboolean *bool_)
 
 /**
  * g_i_marshalling_tests_boolean_inout_true_false:
- * bool_: (inout):
+ * @bool_: (inout):
  */
 void
 g_i_marshalling_tests_boolean_inout_true_false (gboolean *bool_)
@@ -66,7 +66,7 @@ g_i_marshalling_tests_boolean_inout_true_false (gboolean *bool_)
 
 /**
  * g_i_marshalling_tests_boolean_inout_false_true:
- * bool_: (inout):
+ * @bool_: (inout):
  */
 void
 g_i_marshalling_tests_boolean_inout_false_true (gboolean *bool_)
@@ -104,7 +104,7 @@ g_i_marshalling_tests_int8_in_min (gint8 int8)
 
 /**
  * g_i_marshalling_tests_int8_out_max:
- * int8: (out):
+ * @int8: (out):
  */
 void
 g_i_marshalling_tests_int8_out_max (gint8 *int8)
@@ -114,7 +114,7 @@ g_i_marshalling_tests_int8_out_max (gint8 *int8)
 
 /**
  * g_i_marshalling_tests_int8_out_min:
- * int8: (out):
+ * @int8: (out):
  */
 void
 g_i_marshalling_tests_int8_out_min (gint8 *int8)
@@ -124,7 +124,7 @@ g_i_marshalling_tests_int8_out_min (gint8 *int8)
 
 /**
  * g_i_marshalling_tests_int8_inout_max_min:
- * int8: (inout):
+ * @int8: (inout):
  */
 void
 g_i_marshalling_tests_int8_inout_max_min (gint8 *int8)
@@ -135,7 +135,7 @@ g_i_marshalling_tests_int8_inout_max_min (gint8 *int8)
 
 /**
  * g_i_marshalling_tests_int8_inout_min_max:
- * int8: (inout):
+ * @int8: (inout):
  */
 void
 g_i_marshalling_tests_int8_inout_min_max (gint8 *int8)
@@ -159,7 +159,7 @@ g_i_marshalling_tests_uint8_in (guint8 uint8)
 
 /**
  * g_i_marshalling_tests_uint8_out:
- * uint8: (out):
+ * @uint8: (out):
  */
 void
 g_i_marshalling_tests_uint8_out (guint8 *uint8)
@@ -169,7 +169,7 @@ g_i_marshalling_tests_uint8_out (guint8 *uint8)
 
 /**
  * g_i_marshalling_tests_uint8_inout:
- * uint8: (inout):
+ * @uint8: (inout):
  */
 void
 g_i_marshalling_tests_uint8_inout (guint8 *uint8)
@@ -205,7 +205,7 @@ g_i_marshalling_tests_int16_in_min (gint16 int16)
 
 /**
  * g_i_marshalling_tests_int16_out_max:
- * int16: (out):
+ * @int16: (out):
  */
 void
 g_i_marshalling_tests_int16_out_max (gint16 *int16)
@@ -215,7 +215,7 @@ g_i_marshalling_tests_int16_out_max (gint16 *int16)
 
 /**
  * g_i_marshalling_tests_int16_out_min:
- * int16: (out):
+ * @int16: (out):
  */
 void
 g_i_marshalling_tests_int16_out_min (gint16 *int16)
@@ -225,7 +225,7 @@ g_i_marshalling_tests_int16_out_min (gint16 *int16)
 
 /**
  * g_i_marshalling_tests_int16_inout_max_min:
- * int16: (inout):
+ * @int16: (inout):
  */
 void
 g_i_marshalling_tests_int16_inout_max_min (gint16 *int16)
@@ -236,7 +236,7 @@ g_i_marshalling_tests_int16_inout_max_min (gint16 *int16)
 
 /**
  * g_i_marshalling_tests_int16_inout_min_max:
- * int16: (inout):
+ * @int16: (inout):
  */
 void
 g_i_marshalling_tests_int16_inout_min_max (gint16 *int16)
@@ -260,7 +260,7 @@ g_i_marshalling_tests_uint16_in (guint16 uint16)
 
 /**
  * g_i_marshalling_tests_uint16_out:
- * uint16: (out):
+ * @uint16: (out):
  */
 void
 g_i_marshalling_tests_uint16_out (guint16 *uint16)
@@ -270,7 +270,7 @@ g_i_marshalling_tests_uint16_out (guint16 *uint16)
 
 /**
  * g_i_marshalling_tests_uint16_inout:
- * uint16: (inout):
+ * @uint16: (inout):
  */
 void
 g_i_marshalling_tests_uint16_inout (guint16 *uint16)
@@ -306,7 +306,7 @@ g_i_marshalling_tests_int32_in_min (gint32 int32)
 
 /**
  * g_i_marshalling_tests_int32_out_max:
- * int32: (out):
+ * @int32: (out):
  */
 void
 g_i_marshalling_tests_int32_out_max (gint32 *int32)
@@ -316,7 +316,7 @@ g_i_marshalling_tests_int32_out_max (gint32 *int32)
 
 /**
  * g_i_marshalling_tests_int32_out_min:
- * int32: (out):
+ * @int32: (out):
  */
 void
 g_i_marshalling_tests_int32_out_min (gint32 *int32)
@@ -326,7 +326,7 @@ g_i_marshalling_tests_int32_out_min (gint32 *int32)
 
 /**
  * g_i_marshalling_tests_int32_inout_max_min:
- * int32: (inout):
+ * @int32: (inout):
  */
 void
 g_i_marshalling_tests_int32_inout_max_min (gint32 *int32)
@@ -337,7 +337,7 @@ g_i_marshalling_tests_int32_inout_max_min (gint32 *int32)
 
 /**
  * g_i_marshalling_tests_int32_inout_min_max:
- * int32: (inout):
+ * @int32: (inout):
  */
 void
 g_i_marshalling_tests_int32_inout_min_max (gint32 *int32)
@@ -361,7 +361,7 @@ g_i_marshalling_tests_uint32_in (guint32 uint32)
 
 /**
  * g_i_marshalling_tests_uint32_out:
- * uint32: (out):
+ * @uint32: (out):
  */
 void
 g_i_marshalling_tests_uint32_out (guint32 *uint32)
@@ -371,7 +371,7 @@ g_i_marshalling_tests_uint32_out (guint32 *uint32)
 
 /**
  * g_i_marshalling_tests_uint32_inout:
- * uint32: (inout):
+ * @uint32: (inout):
  */
 void
 g_i_marshalling_tests_uint32_inout (guint32 *uint32)
@@ -407,7 +407,7 @@ g_i_marshalling_tests_int64_in_min (gint64 int64)
 
 /**
  * g_i_marshalling_tests_int64_out_max:
- * int64: (out):
+ * @int64: (out):
  */
 void
 g_i_marshalling_tests_int64_out_max (gint64 *int64)
@@ -417,7 +417,7 @@ g_i_marshalling_tests_int64_out_max (gint64 *int64)
 
 /**
  * g_i_marshalling_tests_int64_out_min:
- * int64: (out):
+ * @int64: (out):
  */
 void
 g_i_marshalling_tests_int64_out_min (gint64 *int64)
@@ -427,7 +427,7 @@ g_i_marshalling_tests_int64_out_min (gint64 *int64)
 
 /**
  * g_i_marshalling_tests_int64_inout_max_min:
- * int64: (inout):
+ * @int64: (inout):
  */
 void
 g_i_marshalling_tests_int64_inout_max_min (gint64 *int64)
@@ -438,7 +438,7 @@ g_i_marshalling_tests_int64_inout_max_min (gint64 *int64)
 
 /**
  * g_i_marshalling_tests_int64_inout_min_max:
- * int64: (inout):
+ * @int64: (inout):
  */
 void
 g_i_marshalling_tests_int64_inout_min_max (gint64 *int64)
@@ -462,7 +462,7 @@ g_i_marshalling_tests_uint64_in (guint64 uint64)
 
 /**
  * g_i_marshalling_tests_uint64_out:
- * uint64: (out):
+ * @uint64: (out):
  */
 void
 g_i_marshalling_tests_uint64_out (guint64 *uint64)
@@ -472,7 +472,7 @@ g_i_marshalling_tests_uint64_out (guint64 *uint64)
 
 /**
  * g_i_marshalling_tests_uint64_inout:
- * uint64: (inout):
+ * @uint64: (inout):
  */
 void
 g_i_marshalling_tests_uint64_inout (guint64 *uint64)
@@ -508,7 +508,7 @@ g_i_marshalling_tests_short_in_min (gshort short_)
 
 /**
  * g_i_marshalling_tests_short_out_max:
- * short_: (out):
+ * @short_: (out):
  */
 void
 g_i_marshalling_tests_short_out_max (gshort *short_)
@@ -518,7 +518,7 @@ g_i_marshalling_tests_short_out_max (gshort *short_)
 
 /**
  * g_i_marshalling_tests_short_out_min:
- * short_: (out):
+ * @short_: (out):
  */
 void
 g_i_marshalling_tests_short_out_min (gshort *short_)
@@ -528,7 +528,7 @@ g_i_marshalling_tests_short_out_min (gshort *short_)
 
 /**
  * g_i_marshalling_tests_short_inout_max_min:
- * short_: (inout):
+ * @short_: (inout):
  */
 void
 g_i_marshalling_tests_short_inout_max_min (gshort *short_)
@@ -539,7 +539,7 @@ g_i_marshalling_tests_short_inout_max_min (gshort *short_)
 
 /**
  * g_i_marshalling_tests_short_inout_min_max:
- * short_: (inout):
+ * @short_: (inout):
  */
 void
 g_i_marshalling_tests_short_inout_min_max (gshort *short_)
@@ -563,7 +563,7 @@ g_i_marshalling_tests_ushort_in (gushort ushort)
 
 /**
  * g_i_marshalling_tests_ushort_out:
- * ushort: (out):
+ * @ushort: (out):
  */
 void
 g_i_marshalling_tests_ushort_out (gushort *ushort)
@@ -573,7 +573,7 @@ g_i_marshalling_tests_ushort_out (gushort *ushort)
 
 /**
  * g_i_marshalling_tests_ushort_inout:
- * ushort: (inout):
+ * @ushort: (inout):
  */
 void
 g_i_marshalling_tests_ushort_inout (gushort *ushort)
@@ -609,7 +609,7 @@ g_i_marshalling_tests_int_in_min (gint int_)
 
 /**
  * g_i_marshalling_tests_int_out_max:
- * int_: (out):
+ * @int_: (out):
  */
 void
 g_i_marshalling_tests_int_out_max (gint *int_)
@@ -619,7 +619,7 @@ g_i_marshalling_tests_int_out_max (gint *int_)
 
 /**
  * g_i_marshalling_tests_int_out_min:
- * int_: (out):
+ * @int_: (out):
  */
 void
 g_i_marshalling_tests_int_out_min (gint *int_)
@@ -629,7 +629,7 @@ g_i_marshalling_tests_int_out_min (gint *int_)
 
 /**
  * g_i_marshalling_tests_int_inout_max_min:
- * int_: (inout):
+ * @int_: (inout):
  */
 void
 g_i_marshalling_tests_int_inout_max_min (gint *int_)
@@ -640,7 +640,7 @@ g_i_marshalling_tests_int_inout_max_min (gint *int_)
 
 /**
  * g_i_marshalling_tests_int_inout_min_max:
- * int_: (inout):
+ * @int_: (inout):
  */
 void
 g_i_marshalling_tests_int_inout_min_max (gint *int_)
@@ -664,7 +664,7 @@ g_i_marshalling_tests_uint_in (guint uint)
 
 /**
  * g_i_marshalling_tests_uint_out:
- * uint: (out):
+ * @uint: (out):
  */
 void
 g_i_marshalling_tests_uint_out (guint *uint)
@@ -674,7 +674,7 @@ g_i_marshalling_tests_uint_out (guint *uint)
 
 /**
  * g_i_marshalling_tests_uint_inout:
- * uint: (inout):
+ * @uint: (inout):
  */
 void
 g_i_marshalling_tests_uint_inout (guint *uint)
@@ -710,7 +710,7 @@ g_i_marshalling_tests_long_in_min (glong long_)
 
 /**
  * g_i_marshalling_tests_long_out_max:
- * long_: (out):
+ * @long_: (out):
  */
 void
 g_i_marshalling_tests_long_out_max (glong *long_)
@@ -720,7 +720,7 @@ g_i_marshalling_tests_long_out_max (glong *long_)
 
 /**
  * g_i_marshalling_tests_long_out_min:
- * long_: (out):
+ * @long_: (out):
  */
 void
 g_i_marshalling_tests_long_out_min (glong *long_)
@@ -730,7 +730,7 @@ g_i_marshalling_tests_long_out_min (glong *long_)
 
 /**
  * g_i_marshalling_tests_long_inout_max_min:
- * long_: (inout):
+ * @long_: (inout):
  */
 void
 g_i_marshalling_tests_long_inout_max_min (glong *long_)
@@ -741,7 +741,7 @@ g_i_marshalling_tests_long_inout_max_min (glong *long_)
 
 /**
  * g_i_marshalling_tests_long_inout_min_max:
- * long_: (inout):
+ * @long_: (inout):
  */
 void
 g_i_marshalling_tests_long_inout_min_max (glong *long_)
@@ -765,7 +765,7 @@ g_i_marshalling_tests_ulong_in (gulong ulong)
 
 /**
  * g_i_marshalling_tests_ulong_out:
- * ulong: (out):
+ * @ulong: (out):
  */
 void
 g_i_marshalling_tests_ulong_out (gulong *ulong)
@@ -775,7 +775,7 @@ g_i_marshalling_tests_ulong_out (gulong *ulong)
 
 /**
  * g_i_marshalling_tests_ulong_inout:
- * ulong: (inout):
+ * @ulong: (inout):
  */
 void
 g_i_marshalling_tests_ulong_inout (gulong *ulong)
@@ -811,7 +811,7 @@ g_i_marshalling_tests_ssize_in_min (gssize ssize)
 
 /**
  * g_i_marshalling_tests_ssize_out_max:
- * ssize: (out):
+ * @ssize: (out):
  */
 void
 g_i_marshalling_tests_ssize_out_max (gssize *ssize)
@@ -821,7 +821,7 @@ g_i_marshalling_tests_ssize_out_max (gssize *ssize)
 
 /**
  * g_i_marshalling_tests_ssize_out_min:
- * ssize: (out):
+ * @ssize: (out):
  */
 void
 g_i_marshalling_tests_ssize_out_min (gssize *ssize)
@@ -831,7 +831,7 @@ g_i_marshalling_tests_ssize_out_min (gssize *ssize)
 
 /**
  * g_i_marshalling_tests_ssize_inout_max_min:
- * ssize: (inout):
+ * @ssize: (inout):
  */
 void
 g_i_marshalling_tests_ssize_inout_max_min (gssize *ssize)
@@ -842,7 +842,7 @@ g_i_marshalling_tests_ssize_inout_max_min (gssize *ssize)
 
 /**
  * g_i_marshalling_tests_ssize_inout_min_max:
- * ssize: (inout):
+ * @ssize: (inout):
  */
 void
 g_i_marshalling_tests_ssize_inout_min_max (gssize *ssize)
@@ -866,7 +866,7 @@ g_i_marshalling_tests_size_in (gsize size)
 
 /**
  * g_i_marshalling_tests_size_out:
- * size: (out):
+ * @size: (out):
  */
 void
 g_i_marshalling_tests_size_out (gsize *size)
@@ -876,7 +876,7 @@ g_i_marshalling_tests_size_out (gsize *size)
 
 /**
  * g_i_marshalling_tests_size_inout:
- * size: (inout):
+ * @size: (inout):
  */
 void
 g_i_marshalling_tests_size_inout (gsize *size)
@@ -900,7 +900,7 @@ g_i_marshalling_tests_float_in (gfloat float_)
 
 /**
  * g_i_marshalling_tests_float_out:
- * float_: (out):
+ * @float_: (out):
  */
 void
 g_i_marshalling_tests_float_out (gfloat *float_)
@@ -910,7 +910,7 @@ g_i_marshalling_tests_float_out (gfloat *float_)
 
 /**
  * g_i_marshalling_tests_float_inout:
- * float_: (inout):
+ * @float_: (inout):
  */
 void
 g_i_marshalling_tests_float_inout (gfloat *float_)
@@ -934,7 +934,7 @@ g_i_marshalling_tests_double_in (gdouble double_)
 
 /**
  * g_i_marshalling_tests_double_out:
- * double_: (out):
+ * @double_: (out):
  */
 void
 g_i_marshalling_tests_double_out (gdouble *double_)
@@ -944,7 +944,7 @@ g_i_marshalling_tests_double_out (gdouble *double_)
 
 /**
  * g_i_marshalling_tests_double_inout:
- * double_: (inout):
+ * @double_: (inout):
  */
 void
 g_i_marshalling_tests_double_inout (gdouble *double_)
@@ -968,7 +968,7 @@ g_i_marshalling_tests_time_t_in (time_t time_t_)
 
 /**
  * g_i_marshalling_tests_time_t_out:
- * time_t_: (out):
+ * @time_t_: (out):
  */
 void
 g_i_marshalling_tests_time_t_out (time_t *time_t_)
@@ -978,7 +978,7 @@ g_i_marshalling_tests_time_t_out (time_t *time_t_)
 
 /**
  * g_i_marshalling_tests_time_t_inout:
- * time_t_: (inout):
+ * @time_t_: (inout):
  */
 void
 g_i_marshalling_tests_time_t_inout (time_t *time_t_)
@@ -1002,7 +1002,7 @@ g_i_marshalling_tests_gtype_in (GType gtype)
 
 /**
  * g_i_marshalling_tests_gtype_out:
- * gtype: (out):
+ * @gtype: (out):
  */
 void
 g_i_marshalling_tests_gtype_out (GType *gtype)
@@ -1012,7 +1012,7 @@ g_i_marshalling_tests_gtype_out (GType *gtype)
 
 /**
  * g_i_marshalling_tests_gtype_inout:
- * gtype: (inout):
+ * @gtype: (inout):
  */
 void
 g_i_marshalling_tests_gtype_inout (GType *gtype)
@@ -1049,7 +1049,7 @@ g_i_marshalling_tests_utf8_full_in (gchar *utf8)
 
 /**
  * g_i_marshalling_tests_utf8_none_out:
- * utf8: (out) (transfer none):
+ * @utf8: (out) (transfer none):
  */
 void
 g_i_marshalling_tests_utf8_none_out (gchar **utf8)
@@ -1059,7 +1059,7 @@ g_i_marshalling_tests_utf8_none_out (gchar **utf8)
 
 /**
  * g_i_marshalling_tests_utf8_full_out:
- * utf8: (out) (transfer full):
+ * @utf8: (out) (transfer full):
  */
 void
 g_i_marshalling_tests_utf8_full_out (gchar **utf8)
@@ -1069,7 +1069,7 @@ g_i_marshalling_tests_utf8_full_out (gchar **utf8)
 
 /**
  * g_i_marshalling_tests_utf8_dangling_out:
- * utf8: (out) (transfer full):
+ * @utf8: (out) (transfer full):
  */
 void
 g_i_marshalling_tests_utf8_dangling_out (gchar **utf8)
@@ -1083,7 +1083,7 @@ g_i_marshalling_tests_utf8_dangling_out (gchar **utf8)
 
 /**
  * g_i_marshalling_tests_utf8_none_inout:
- * utf8: (inout) (transfer none):
+ * @utf8: (inout) (transfer none):
  */
 void
 g_i_marshalling_tests_utf8_none_inout (gchar **utf8)
@@ -1094,7 +1094,7 @@ g_i_marshalling_tests_utf8_none_inout (gchar **utf8)
 
 /**
  * g_i_marshalling_tests_utf8_full_inout:
- * utf8: (inout) (transfer full):
+ * @utf8: (inout) (transfer full):
  */
 void
 g_i_marshalling_tests_utf8_full_inout (gchar **utf8)
@@ -1617,7 +1617,8 @@ g_i_marshalling_tests_bytearray_none_in (GByteArray *array_)
 
 /**
  * g_i_marshalling_tests_gstrv_return:
- * Returns:
+ *
+ * Returns: an array of strings
  */
 GStrv
 g_i_marshalling_tests_gstrv_return (void)
@@ -3384,8 +3385,8 @@ g_i_marshalling_tests_test_interface_test_int8_in (GIMarshallingTestsInterface *
 
 /**
  * g_i_marshalling_tests_int_out_out:
- * int0: (out):
- * int1: (out):
+ * @int0: (out):
+ * @int1: (out):
  */
 void
 g_i_marshalling_tests_int_out_out (gint *int0, gint *int1)
@@ -3396,7 +3397,7 @@ g_i_marshalling_tests_int_out_out (gint *int0, gint *int1)
 
 /**
  * g_i_marshalling_tests_int_return_out:
- * int_: (out):
+ * @int_: (out):
  */
 gint
 g_i_marshalling_tests_int_return_out (gint *int_)
diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py
index 01cbb1ac..715ffe47 100644
--- a/giscanner/annotationparser.py
+++ b/giscanner/annotationparser.py
@@ -21,7 +21,6 @@
 # AnnotationParser - parses gtk-doc annotations
 
 import re
-import sys
 
 from .ast import (Array, Bitfield, Callback, Class, Enum, Field, Function,
                   Interface, List, Map, Parameter, Property, Record, Return,
@@ -49,7 +48,6 @@ TAG_VFUNC = 'virtual'
 TAG_SINCE = 'since'
 TAG_DEPRECATED = 'deprecated'
 TAG_RETURNS = 'returns'
-TAG_RETURNS_ALT = 'return value'
 TAG_ATTRIBUTES = 'attributes'
 TAG_RENAME_TO = 'rename to'
 TAG_TYPE = 'type'
@@ -100,14 +98,7 @@ class DocBlock(object):
         return '<DocBlock %r %r>' % (self.name, self.options)
 
     def get(self, name):
-        if name == TAG_RETURNS:
-            value = self.tags.get(name)
-            if value is None:
-                return self.tags.get(TAG_RETURNS_ALT)
-            else:
-                return value
-        else:
-            return self.tags.get(name)
+        return self.tags.get(name)
 
 
 class DocTag(object):
@@ -152,6 +143,10 @@ class Option(object):
 
 
 class AnnotationParser(object):
+    WHITESPACE_RE = re.compile(r'^\s*$')
+    ASCII_TEXT_RE = re.compile(r'\s*[A-Za-z]+')
+    OPTION_RE = re.compile(r'\([A-Za-z]+[^(]*\)')
+    RETURNS_RE = re.compile(r'^return(s?)( value)?:', re.IGNORECASE)
 
     def __init__(self, namespace, source_scanner, transformer):
         self._blocks = {}
@@ -195,64 +190,97 @@ class AnnotationParser(object):
         cpos = block_header.find(': ')
         if cpos:
             block_name = block_header[:cpos]
-            block_options, rest = self._parse_options(block_header[cpos+2:])
-            if rest:
-                return
+            block_options = self.parse_options(block_header[cpos+2:])
         else:
             block_name, block_options = block_header, {}
         block = DocBlock(block_name, block_options)
+        debug = block_name == 'annotation_object_compute_sum_n'
         comment_lines = []
-        parse_parameters = True
-        canon_name = ''
+        parsing_parameters = True
+        last_param_tag = None
+
+        # Second phase: parse parameters, return values, Tag: format
+        # annotations.
+        #
+        # Valid lines look like:
+        # * @foo: some comment here
+        # * @baz: (inout): This has an annotation
+        # * @bar: (out) (allow-none): this is a long parameter comment
+        # *  that gets wrapped to the next line.
+        # *
+        # * Some documentation for the function.
+        # *
+        # * Returns: (transfer none): A value
         for line in comment[pos+1:].split('\n'):
             line = line.lstrip()
-            line = line[2:].strip() # Skip ' *'
-            if not line:
-                if parse_parameters:
-                    parse_parameters = False
+            if (not line.startswith('*') or
+                self.WHITESPACE_RE.match(line[1:])):
+                # As soon as we find a line that's just whitespace,
+                # we're done parsing the parameters.
+                parsing_parameters = False
                 continue
-            if line.startswith('@'):
-                line = line[1:]
-            elif not ': ' in line:
-                if parse_parameters and line:
-                    if canon_name != '' and canon_name in block.tags:
-                        block.tags[canon_name].comment += ' ' + line
+
+            line = line[1:].lstrip()
+
+            # Look for a parameter or return value.  Both of these can
+            # have parenthesized options.
+            first_colonspace_index = line.find(': ')
+            is_parameter = line.startswith('@')
+            is_return_value = self.RETURNS_RE.search(line)
+            if ((is_parameter or is_return_value)
+                and first_colonspace_index > 0):
+                if is_parameter:
+                    argname = line[1:first_colonspace_index]
+                else:
+                    argname = TAG_RETURNS
+                tag = DocTag(argname)
+                second_colon_index = line.rfind(':')
+                found_options = False
+                if second_colon_index > first_colonspace_index:
+                    value_line = \
+                      line[first_colonspace_index+2:second_colon_index]
+                    if self.OPTION_RE.search(value_line):
+                        # The OPTION_RE is a little bit heuristic.  If
+                        # we found two colons, we scan inside for something
+                        # that looks like (foo).
+                        # *Ideally* we'd change the gtk-doc format to
+                        # require double colons, and then there'd be
+                        # no ambiguity.  I.e.:
+                        # @foo:: Some documentation here
+                        # But that'd be a rather incompatible change.
+                        found_options = True
+                        tag.comment = line[second_colon_index+1:].strip()
+                        tag.options = self.parse_options(value_line)
+                if not found_options:
+                    # We didn't find any options, so just take the whole thing
+                    # as documentation.
+                    tag.comment = line[first_colonspace_index+2:].strip()
+                block.tags[argname] = tag
+                last_param_tag = tag
+            elif (not is_parameter) and parsing_parameters and last_param_tag:
+                # We need to handle continuation lines on parameters.  The
+                # conditional above - if a line doesn't start with '@', we're
+                # not yet in the documentation block for the whole function,
+                # and we've seen at least one parameter.
+                last_param_tag.comment += (' ' + line.strip())
+            elif first_colonspace_index > 0:
+                # The line is of the form "Tag: some value here", like:
+                # Since: 0.8
+                tag_name = line[:first_colonspace_index]
+                if self.ASCII_TEXT_RE.match(tag_name):
+                    tag_name = tag_name.lower()
+                    tag = DocTag(tag_name)
+                    tag.value = line[first_colonspace_index+2:]
+                    block.tags[tag_name] = tag
                 else:
                     comment_lines.append(line)
-                continue
-            tag_name, value = self._split_tag_namevalue(line)
-            canon_name = tag_name.lower()
-            if canon_name in block.tags:
-                print >> sys.stderr, (
-                    "Symbol %s has multiple definition of tag %r" % (
-                    block_name, canon_name, ))
-            block.tags[canon_name] = self._create_tag(canon_name, value)
+            elif (not is_parameter):
+                comment_lines.append(line)
         block.comment = '\n'.join(comment_lines)
         self._blocks[block.name] = block
 
-    def _split_tag_namevalue(self, raw):
-        """Split a line into tag name and value"""
-        parts = raw.split(': ', 1)
-        if len(parts) == 1:
-            tag_name = parts[0]
-            value = ''
-            if tag_name.endswith(':'):
-                tag_name = tag_name[:-1]
-        else:
-            tag_name, value = parts
-        return (tag_name, value)
-
-    def _create_tag(self, tag_name, value):
-        # Tag: bar
-        # Tag: bar opt1 opt2
-        tag = DocTag(tag_name)
-        tag.value = value
-        options, rest = self._parse_options(tag.value)
-        tag.options = options
-        tag.comment = rest or ''
-        return tag
-
-    def _parse_options(self, value):
+    @classmethod
+    def parse_options(cls, value):
         # (foo)
         # (bar opt1 opt2...)
         opened = -1
@@ -277,11 +305,7 @@ class AnnotationParser(object):
                 last = i + 2
                 opened = -1
 
-        if last is not None:
-            rest = value[last:].strip()
-        else:
-            rest = None
-        return options, rest
+        return options
 
 
 class AnnotationApplier(object):
@@ -871,7 +895,8 @@ class AnnotationApplier(object):
         annos_tag = self._get_tag(block, TAG_ATTRIBUTES)
         if annos_tag is None:
             return
-        for key, value in annos_tag.options.iteritems():
+        options = AnnotationParser.parse_options(annos_tag.value)
+        for key, value in options.iteritems():
             if value:
                 node.attributes.append((key, value.one()))
 
diff --git a/tests/scanner/annotation-1.0-expected.gir b/tests/scanner/annotation-1.0-expected.gir
index 12025ed8..cf974f5e 100644
--- a/tests/scanner/annotation-1.0-expected.gir
+++ b/tests/scanner/annotation-1.0-expected.gir
@@ -83,14 +83,14 @@ and/or use gtk-doc annotations.  -->
            glib:type-struct="ObjectClass">
       <attribute name="org.example.Test" value="cows"/>
       <method name="method" c:identifier="annotation_object_method">
-        <return-value transfer-ownership="none">
+        <return-value transfer-ownership="none" doc="an int">
           <type name="int" c:type="gint"/>
         </return-value>
       </method>
       <method name="out"
               c:identifier="annotation_object_out"
               doc="This is a test for out arguments">
-        <return-value transfer-ownership="none">
+        <return-value transfer-ownership="none" doc="an int">
           <type name="int" c:type="gint"/>
         </return-value>
         <parameters>
@@ -129,7 +129,7 @@ and/or use gtk-doc annotations.  -->
       <method name="inout"
               c:identifier="annotation_object_inout"
               doc="This is a test for out arguments">
-        <return-value transfer-ownership="none">
+        <return-value transfer-ownership="none" doc="an int">
           <type name="int" c:type="gint"/>
         </return-value>
         <parameters>
@@ -145,7 +145,7 @@ and/or use gtk-doc annotations.  -->
       <method name="inout2"
               c:identifier="annotation_object_inout2"
               doc="This is a second test for out arguments">
-        <return-value transfer-ownership="none">
+        <return-value transfer-ownership="none" doc="an int">
           <type name="int" c:type="gint"/>
         </return-value>
         <parameters>
@@ -161,7 +161,7 @@ and/or use gtk-doc annotations.  -->
       <method name="inout3"
               c:identifier="annotation_object_inout3"
               doc="This is a 3th test for out arguments">
-        <return-value transfer-ownership="none">
+        <return-value transfer-ownership="none" doc="an int">
           <type name="int" c:type="gint"/>
         </return-value>
         <parameters>
@@ -178,7 +178,7 @@ and/or use gtk-doc annotations.  -->
       <method name="in"
               c:identifier="annotation_object_in"
               doc="This is a test for in arguments">
-        <return-value transfer-ownership="none">
+        <return-value transfer-ownership="none" doc="an int">
           <type name="int" c:type="gint"/>
         </return-value>
         <parameters>
@@ -192,7 +192,7 @@ and/or use gtk-doc annotations.  -->
       <method name="calleeowns"
               c:identifier="annotation_object_calleeowns"
               doc="This is a test for out arguments; GObject defaults to transfer">
-        <return-value transfer-ownership="none">
+        <return-value transfer-ownership="none" doc="an int">
           <type name="int" c:type="gint"/>
         </return-value>
         <parameters>
@@ -208,7 +208,7 @@ and/or use gtk-doc annotations.  -->
       <method name="calleesowns"
               c:identifier="annotation_object_calleesowns"
               doc="This is a test for out arguments, one transferred, other not">
-        <return-value transfer-ownership="none">
+        <return-value transfer-ownership="none" doc="an int">
           <type name="int" c:type="gint"/>
         </return-value>
         <parameters>
@@ -312,7 +312,9 @@ intentionally similar example to gtk_container_get_children">
               <type name="int"/>
             </array>
           </parameter>
-          <parameter name="n_nums" transfer-ownership="none">
+          <parameter name="n_nums"
+                     transfer-ownership="none"
+                     doc="Length of number array">
             <type name="int" c:type="int"/>
           </parameter>
         </parameters>
@@ -331,7 +333,9 @@ intentionally similar example to gtk_container_get_children">
               <type name="int"/>
             </array>
           </parameter>
-          <parameter name="n_nums" transfer-ownership="none">
+          <parameter name="n_nums"
+                     transfer-ownership="none"
+                     doc="Length of number array">
             <type name="int" c:type="int"/>
           </parameter>
         </parameters>
@@ -364,7 +368,7 @@ intentionally similar example to gtk_container_get_children">
       <method name="string_out"
               c:identifier="annotation_object_string_out"
               doc="Test returning a string as an out parameter">
-        <return-value transfer-ownership="none">
+        <return-value transfer-ownership="none" doc="some boolean">
           <type name="boolean" c:type="gboolean"/>
         </return-value>
         <parameters>
@@ -391,7 +395,9 @@ intentionally similar example to gtk_container_get_children">
                      doc="Callback to invoke">
             <type name="ForeachFunc" c:type="AnnotationForeachFunc"/>
           </parameter>
-          <parameter name="user_data" transfer-ownership="none">
+          <parameter name="user_data"
+                     transfer-ownership="none"
+                     doc="Callback user data">
             <type name="any" c:type="gpointer"/>
           </parameter>
         </parameters>
@@ -408,7 +414,9 @@ intentionally similar example to gtk_container_get_children">
               <type name="uint8"/>
             </array>
           </parameter>
-          <parameter name="length" transfer-ownership="none">
+          <parameter name="length"
+                     transfer-ownership="none"
+                     doc="Length of the data">
             <type name="size_t" c:type="gsize"/>
           </parameter>
         </parameters>
@@ -425,7 +433,9 @@ intentionally similar example to gtk_container_get_children">
               <type name="int8"/>
             </array>
           </parameter>
-          <parameter name="length" transfer-ownership="none">
+          <parameter name="length"
+                     transfer-ownership="none"
+                     doc="Length of the data">
             <type name="size_t" c:type="gsize"/>
           </parameter>
         </parameters>
@@ -443,7 +453,9 @@ type.">
               <type name="uint8"/>
             </array>
           </parameter>
-          <parameter name="length" transfer-ownership="none">
+          <parameter name="length"
+                     transfer-ownership="none"
+                     doc="Length of the data">
             <type name="size_t" c:type="gsize"/>
           </parameter>
         </parameters>
@@ -467,13 +479,19 @@ type.">
                      transfer-ownership="none"
                      scope="notified"
                      closure="2"
-                     destroy="3">
+                     destroy="3"
+                     doc="The callback">
             <type name="ForeachFunc" c:type="AnnotationForeachFunc"/>
           </parameter>
-          <parameter name="user_data" transfer-ownership="none">
+          <parameter name="user_data"
+                     transfer-ownership="none"
+                     doc="The callback data">
             <type name="any" c:type="gpointer"/>
           </parameter>
-          <parameter name="destroy" transfer-ownership="none" scope="call">
+          <parameter name="destroy"
+                     transfer-ownership="none"
+                     scope="call"
+                     doc="Destroy notification">
             <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/>
           </parameter>
         </parameters>
@@ -526,7 +544,7 @@ type.">
           <type name="none" c:type="void"/>
         </return-value>
         <parameters>
-          <parameter name="arg1" transfer-ownership="none">
+          <parameter name="object" transfer-ownership="none">
             <type name="any" c:type="gpointer"/>
           </parameter>
         </parameters>
@@ -586,7 +604,9 @@ it says it&apos;s pointer but it&apos;s actually a string."
         <type name="int" c:type="gint"/>
       </return-value>
       <parameters>
-        <parameter name="object" transfer-ownership="none">
+        <parameter name="object"
+                   transfer-ownership="none"
+                   doc="A #AnnotationObject.">
           <type name="Object" c:type="AnnotationObject*"/>
         </parameter>
         <parameter name="data" transfer-ownership="none" doc="Some data.">
@@ -648,6 +668,19 @@ detection, and fixing it via annotations.">
         </parameter>
       </parameters>
     </function>
+    <function name="invalid_annotation"
+              c:identifier="annotation_invalid_annotation">
+      <return-value transfer-ownership="none">
+        <type name="none" c:type="void"/>
+      </return-value>
+      <parameters>
+        <parameter name="foo"
+                   transfer-ownership="none"
+                   doc="some text (e.g. example) or else">
+          <type name="int" c:type="int"/>
+        </parameter>
+      </parameters>
+    </function>
     <function name="ptr_array" c:identifier="annotation_ptr_array">
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
diff --git a/tests/scanner/annotation-1.0-expected.tgir b/tests/scanner/annotation-1.0-expected.tgir
index 0f8a5fe7..d8dfc381 100644
--- a/tests/scanner/annotation-1.0-expected.tgir
+++ b/tests/scanner/annotation-1.0-expected.tgir
@@ -383,7 +383,7 @@
           <type name="none"/>
         </return-value>
         <parameters>
-          <parameter name="arg1" transfer-ownership="none">
+          <parameter name="object" transfer-ownership="none">
             <type name="any"/>
           </parameter>
         </parameters>
@@ -476,6 +476,16 @@
         </parameter>
       </parameters>
     </function>
+    <function name="invalid_annotation" c:identifier="annotation_invalid_annotation">
+      <return-value transfer-ownership="none">
+        <type name="none"/>
+      </return-value>
+      <parameters>
+        <parameter name="foo" transfer-ownership="none">
+          <type name="int"/>
+        </parameter>
+      </parameters>
+    </function>
     <function name="ptr_array" c:identifier="annotation_ptr_array">
       <return-value transfer-ownership="none">
         <type name="none"/>
diff --git a/tests/scanner/annotation.c b/tests/scanner/annotation.c
index 64f9cc32..497d1eec 100644
--- a/tests/scanner/annotation.c
+++ b/tests/scanner/annotation.c
@@ -641,7 +641,7 @@ annotation_string_zero_terminated (void)
 
 /**
  * annotation_string_zero_terminated_out:
- * @out: (array zero-terminated=1) (inout)
+ * @out: (array zero-terminated=1) (inout):
  **/
 void
 annotation_string_zero_terminated_out (char ***out)
@@ -737,4 +737,15 @@ annotation_attribute_func (AnnotationObject *object,
   return 42;
 }
 
+/**
+ * annotation_invalid_annotation:
+ * @foo: some text (e.g. example) or else
+ */
+void
+annotation_invalid_annotation (int foo)
+{
+
+}
+
+
 char backslash_parsing_tester_2 = '\\';
diff --git a/tests/scanner/annotation.h b/tests/scanner/annotation.h
index ace36515..e4f29065 100644
--- a/tests/scanner/annotation.h
+++ b/tests/scanner/annotation.h
@@ -142,6 +142,8 @@ void     annotation_set_source_file (const char *fname);
 gint     annotation_attribute_func (AnnotationObject *object,
                                     const gchar      *data);
 
+void     annotation_invalid_annotation (int foo);
+
 /**
  * AnnotationStruct:
  *
diff --git a/tests/scanner/foo-1.0-expected.gir b/tests/scanner/foo-1.0-expected.gir
index 68896c11..f7ca794b 100644
--- a/tests/scanner/foo-1.0-expected.gir
+++ b/tests/scanner/foo-1.0-expected.gir
@@ -334,10 +334,10 @@ uses a C sugar return type.">
           <type name="none" c:type="void"/>
         </return-value>
         <parameters>
-          <parameter name="offset" transfer-ownership="none">
+          <parameter name="offset" transfer-ownership="none" doc="offset">
             <type name="int" c:type="int"/>
           </parameter>
-          <parameter name="length" transfer-ownership="none">
+          <parameter name="length" transfer-ownership="none" doc="length">
             <type name="int" c:type="int"/>
           </parameter>
         </parameters>
@@ -443,10 +443,10 @@ uses a C sugar return type.">
           <type name="none" c:type="void"/>
         </return-value>
         <parameters>
-          <parameter name="offset" transfer-ownership="none">
+          <parameter name="offset" transfer-ownership="none" doc="offset">
             <type name="int" c:type="int"/>
           </parameter>
-          <parameter name="length" transfer-ownership="none">
+          <parameter name="length" transfer-ownership="none" doc="length">
             <type name="int" c:type="int"/>
           </parameter>
         </parameters>
@@ -515,10 +515,10 @@ uses a C sugar return type.">
             <parameter name="object" transfer-ownership="none">
               <type name="Object" c:type="FooObject*"/>
             </parameter>
-            <parameter name="offset" transfer-ownership="none">
+            <parameter name="offset" transfer-ownership="none" doc="offset">
               <type name="int" c:type="int"/>
             </parameter>
-            <parameter name="length" transfer-ownership="none">
+            <parameter name="length" transfer-ownership="none" doc="length">
               <type name="int" c:type="int"/>
             </parameter>
           </parameters>
@@ -570,7 +570,9 @@ uses a C sugar return type.">
           <type name="none" c:type="void"/>
         </return-value>
         <parameters>
-          <parameter name="r2" transfer-ownership="none">
+          <parameter name="r2"
+                     transfer-ownership="none"
+                     doc="source rectangle">
             <type name="Rectangle" c:type="FooRectangle*"/>
           </parameter>
         </parameters>
@@ -826,7 +828,7 @@ exposed to language bindings."
         <type name="none" c:type="void"/>
       </return-value>
       <parameters>
-        <parameter name="fs" transfer-ownership="none">
+        <parameter name="fs" transfer-ownership="none" doc="a #FooSkippable">
           <type name="Skippable" c:type="FooSkippable"/>
         </parameter>
       </parameters>