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

5 files changed, 88 insertions, 30 deletions

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>