scanner: allow multiline annotations

Allow `identifier`, `parameter` and `tag` part `annotations` fields
to span multiple lines

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

4 files changed, 629 insertions, 44 deletions

diff --git a/tests/scanner/annotationparser/gi/identifier_symbol.xml b/tests/scanner/annotationparser/gi/identifier_symbol.xml
index 522f1fa8..fd611cd9 100644
--- a/tests/scanner/annotationparser/gi/identifier_symbol.xml
+++ b/tests/scanner/annotationparser/gi/identifier_symbol.xml
@@ -393,6 +393,9 @@
           <annotation>
             <name>skip</name>
           </annotation>
+          <annotation>
+            <name>foreign</name>
+          </annotation>
         </annotations>
       </identifier>
       <parameters>
@@ -414,20 +417,13 @@
           <description>first parameter</description>
         </parameter>
       </parameters>
-      <description>(foreign)
-Annotations spanning multiple lines are not valid</description>
+      <description>Annotations spanning multiple lines are not valid</description>
     </docblock>
-    <messages>
-      <message>3: Error: Test: ignoring invalid multiline annotation continuation:
- * (foreign)
-   ^</message>
-    </messages>
   </parser>
   <output>/**
- * test_multiline_annotations_on_identifier: (skip)
+ * test_multiline_annotations_on_identifier: (skip) (foreign)
  * @param1: (allow-none) (transfer full): first parameter
  *
- * (foreign)
  * Annotations spanning multiple lines are not valid
  */</output>
 </test>
diff --git a/tests/scanner/annotationparser/gi/parameter.xml b/tests/scanner/annotationparser/gi/parameter.xml
index 43f97b3f..51ba6f5e 100644
--- a/tests/scanner/annotationparser/gi/parameter.xml
+++ b/tests/scanner/annotationparser/gi/parameter.xml
@@ -138,23 +138,24 @@
             <annotation>
               <name>allow-none</name>
             </annotation>
+            <annotation>
+              <name>transfer</name>
+              <options>
+                <option>
+                  <name>full</name>
+                </option>
+              </options>
+            </annotation>
           </annotations>
-          <description>
-(transfer full): first parameter</description>
+          <description>first parameter</description>
         </parameter>
       </parameters>
       <description>Annotations spanning multiple lines are not valid</description>
     </docblock>
-    <messages>
-      <message>4: Error: Test: ignoring invalid multiline annotation continuation:
- * (transfer full): first parameter
-   ^</message>
-    </messages>
   </parser>
   <output>/**
  * test_multiline_annotations_on_parameter:
- * @param1: (allow-none):
- * (transfer full): first parameter
+ * @param1: (allow-none) (transfer full): first parameter
  *
  * Annotations spanning multiple lines are not valid
  */</output>
@@ -202,7 +203,7 @@
  * anjuta_async_notify_get_error:
  *
  * @self: An #AnjutaAsyncNotify object
- * @error: Return location for the error set by the called interface to which 
+ * @error: Return location for the error set by the called interface to which
  *                 this object was passed. If no error is set, @error is set to NULL.
  *
  * Gets the error set on @self.
diff --git a/tests/scanner/annotationparser/gi/syntax_multiline_annotations.xml b/tests/scanner/annotationparser/gi/syntax_multiline_annotations.xml
index 4aa92e42..c2897948 100644
--- a/tests/scanner/annotationparser/gi/syntax_multiline_annotations.xml
+++ b/tests/scanner/annotationparser/gi/syntax_multiline_annotations.xml
@@ -4,6 +4,40 @@
 
 <test>
   <input>/**
+ * regress_forced_method:
+ *   (skip)
+ *   (method)
+ * @obj: A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+        <annotations>
+          <annotation>
+            <name>skip</name>
+          </annotation>
+          <annotation>
+            <name>method</name>
+          </annotation>
+        </annotations>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>obj</name>
+          <description>A #RegressTestObj</description>
+        </parameter>
+      </parameters>
+    </docblock>
+  </parser>
+  <output>/**
+ * regress_forced_method: (skip) (method)
+ * @obj: A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
  * regress_forced_method: (skip)
  * (method)
  * @obj: A #RegressTestObj
@@ -16,6 +50,9 @@
           <annotation>
             <name>skip</name>
           </annotation>
+          <annotation>
+            <name>method</name>
+          </annotation>
         </annotations>
       </identifier>
       <parameters>
@@ -24,19 +61,11 @@
           <description>A #RegressTestObj</description>
         </parameter>
       </parameters>
-      <description>(method)</description>
     </docblock>
-    <messages>
-      <message>3: Error: Test: ignoring invalid multiline annotation continuation:
- * (method)
-   ^</message>
-    </messages>
   </parser>
   <output>/**
- * regress_forced_method: (skip)
+ * regress_forced_method: (skip) (method)
  * @obj: A #RegressTestObj
- *
- * (method)
  */</output>
 </test>
 
@@ -54,6 +83,9 @@
           <annotation>
             <name>skip</name>
           </annotation>
+          <annotation>
+            <name>method</name>
+          </annotation>
         </annotations>
       </identifier>
       <parameters>
@@ -62,19 +94,574 @@
           <description>A #RegressTestObj</description>
         </parameter>
       </parameters>
-      <description>(method)</description>
+    </docblock>
+  </parser>
+  <output>/**
+ * regress_forced_method: (skip) (method)
+ * @obj: A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ *   (skip) (method)
+ * @obj: A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+        <annotations>
+          <annotation>
+            <name>skip</name>
+          </annotation>
+          <annotation>
+            <name>method</name>
+          </annotation>
+        </annotations>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>obj</name>
+          <description>A #RegressTestObj</description>
+        </parameter>
+      </parameters>
+    </docblock>
+  </parser>
+  <output>/**
+ * regress_forced_method: (skip) (method)
+ * @obj: A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ * @obj:
+ *   (skip)
+ *   (nullable): A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>obj</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+            <annotation>
+              <name>nullable</name>
+            </annotation>
+          </annotations>
+          <description>A #RegressTestObj</description>
+        </parameter>
+      </parameters>
+    </docblock>
+  </parser>
+  <output>/**
+ * regress_forced_method:
+ * @obj: (skip) (nullable): A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ * @obj:
+ *   (skip)
+ *   (nullable):
+ *   A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>obj</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+            <annotation>
+              <name>nullable</name>
+            </annotation>
+          </annotations>
+          <description>
+  A #RegressTestObj</description>
+        </parameter>
+      </parameters>
+    </docblock>
+  </parser>
+  <output>/**
+ * regress_forced_method:
+ * @obj: (skip) (nullable):
+ *   A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ * @obj: (skip)
+ * (nullable): A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>obj</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+            <annotation>
+              <name>nullable</name>
+            </annotation>
+          </annotations>
+          <description>A #RegressTestObj</description>
+        </parameter>
+      </parameters>
+    </docblock>
+  </parser>
+  <output>/**
+ * regress_forced_method:
+ * @obj: (skip) (nullable): A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ * @obj: (skip)
+ *     (nullable) A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>obj</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+            <annotation>
+              <name>nullable</name>
+            </annotation>
+          </annotations>
+          <description>A #RegressTestObj</description>
+        </parameter>
+      </parameters>
     </docblock>
     <messages>
-      <message>3: Error: Test: ignoring invalid multiline annotation continuation:
- *     (method)
-       ^</message>
+      <message>4: Warning: Test: missing ":" at column 18:
+ *     (nullable) A #RegressTestObj
+                 ^</message>
     </messages>
   </parser>
   <output>/**
- * regress_forced_method: (skip)
- * @obj: A #RegressTestObj
+ * regress_forced_method:
+ * @obj: (skip) (nullable): A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ * @obj: (skip)
+ *     (skip): A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>obj</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+          </annotations>
+          <description>A #RegressTestObj</description>
+        </parameter>
+      </parameters>
+    </docblock>
+    <messages>
+      <message>4: Error: Test: multiple "skip" annotations:
+ *     (skip): A #RegressTestObj
+            ^
+      </message>
+    </messages>
+  </parser>
+  <output>/**
+ * regress_forced_method:
+ * @obj: (skip): A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
  *
- * (method)
+ * Returns:
+ *   (skip)
+ *   (nullable): A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+            <annotation>
+              <name>nullable</name>
+            </annotation>
+          </annotations>
+          <description>A #RegressTestObj</description>
+        </tag>
+      </tags>
+    </docblock>
+  </parser>
+  <output>/**
+ * regress_forced_method:
+ *
+ * Returns: (skip) (nullable): A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ *
+ * Returns:
+ *   (skip)
+ *   (nullable):
+ *   A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+            <annotation>
+              <name>nullable</name>
+            </annotation>
+          </annotations>
+          <description>
+  A #RegressTestObj</description>
+        </tag>
+      </tags>
+    </docblock>
+  </parser>
+  <output>/**
+ * regress_forced_method:
+ *
+ * Returns: (skip) (nullable):
+ *   A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ *
+ * Returns: (skip)
+ * (nullable): A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+            <annotation>
+              <name>nullable</name>
+            </annotation>
+          </annotations>
+          <description>A #RegressTestObj</description>
+        </tag>
+      </tags>
+    </docblock>
+  </parser>
+  <output>/**
+ * regress_forced_method:
+ *
+ * Returns: (skip) (nullable): A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ *
+ * Returns: (skip)
+ *     (nullable) A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+            <annotation>
+              <name>nullable</name>
+            </annotation>
+          </annotations>
+          <description>A #RegressTestObj</description>
+        </tag>
+      </tags>
+    </docblock>
+    <messages>
+      <message>5: Warning: Test: missing ":" at column 18:
+ *     (nullable) A #RegressTestObj
+                 ^</message>
+    </messages>
+  </parser>
+  <output>/**
+ * regress_forced_method:
+ *
+ * Returns: (skip) (nullable): A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * regress_forced_method:
+ *
+ * Returns: (skip)
+ *     (skip): A #RegressTestObj
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>regress_forced_method</name>
+      </identifier>
+      <tags>
+        <tag>
+          <name>returns</name>
+          <annotations>
+            <annotation>
+              <name>skip</name>
+            </annotation>
+          </annotations>
+          <description>A #RegressTestObj</description>
+        </tag>
+      </tags>
+    </docblock>
+    <messages>
+      <message>5: Error: Test: multiple "skip" annotations:
+ *     (skip): A #RegressTestObj
+            ^
+      </message>
+    </messages>
+  </parser>
+  <output>/**
+ * regress_forced_method:
+ *
+ * Returns: (skip): A #RegressTestObj
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * gtk_window_set_has_frame:
+ * @window: a #GtkWindow
+ * @setting: a boolean
+ *
+ * (Note: this is a special-purpose function for the framebuffer port,
+ *  that causes GTK+ to draw its own window border. For most applications,
+ *  you want gtk_window_set_decorated() instead, which tells the window
+ *  manager whether to draw the window border.)
+ *
+ * If this function is called on a window with setting of %TRUE, before
+ * it is realized or showed, it will have a "frame" window around
+ * @window->window, accessible in @window->frame. Using the signal
+ * frame_event you can receive all events targeted at the frame.
+ *
+ * This function is used by the linux-fb port to implement managed
+ * windows, but it could conceivably be used by X-programs that
+ * want to do their own window decorations.
+ *
+ * Deprecated: 2.24: This function will be removed in GTK+ 3
+ **/</input>
+  <parser>
+<docblock>
+      <identifier>
+        <name>gtk_window_set_has_frame</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>window</name>
+          <description>a #GtkWindow</description>
+        </parameter>
+        <parameter>
+          <name>setting</name>
+          <description>a boolean</description>
+        </parameter>
+      </parameters>
+      <description>(Note: this is a special-purpose function for the framebuffer port,
+ that causes GTK+ to draw its own window border. For most applications,
+ you want gtk_window_set_decorated() instead, which tells the window
+ manager whether to draw the window border.)
+
+If this function is called on a window with setting of %TRUE, before
+it is realized or showed, it will have a "frame" window around
+@window->window, accessible in @window->frame. Using the signal
+frame_event you can receive all events targeted at the frame.
+
+This function is used by the linux-fb port to implement managed
+windows, but it could conceivably be used by X-programs that
+want to do their own window decorations.</description>
+      <tags>
+        <tag>
+          <name>deprecated</name>
+          <value>2.24</value>
+          <description>This function will be removed in GTK+ 3</description>
+        </tag>
+      </tags>
+    </docblock>
+  </parser>
+  <output>/**
+ * gtk_window_set_has_frame:
+ * @window: a #GtkWindow
+ * @setting: a boolean
+ *
+ * (Note: this is a special-purpose function for the framebuffer port,
+ *  that causes GTK+ to draw its own window border. For most applications,
+ *  you want gtk_window_set_decorated() instead, which tells the window
+ *  manager whether to draw the window border.)
+ *
+ * If this function is called on a window with setting of %TRUE, before
+ * it is realized or showed, it will have a "frame" window around
+ * @window->window, accessible in @window->frame. Using the signal
+ * frame_event you can receive all events targeted at the frame.
+ *
+ * This function is used by the linux-fb port to implement managed
+ * windows, but it could conceivably be used by X-programs that
+ * want to do their own window decorations.
+ *
+ * Deprecated: 2.24: This function will be removed in GTK+ 3
+ */</output>
+</test>
+
+<test>
+  <input>/**
+ * gtk_window_set_has_frame:
+ * @window: a #GtkWindow
+ * @setting:
+ * (Note: this is a special-purpose function for the framebuffer port,
+ *  that causes GTK+ to draw its own window border. For most applications,
+ *  you want gtk_window_set_decorated() instead, which tells the window
+ *  manager whether to draw the window border.)
+ *
+ * If this function is called on a window with setting of %TRUE, before
+ * it is realized or showed, it will have a "frame" window around
+ * @window->window, accessible in @window->frame. Using the signal
+ * frame_event you can receive all events targeted at the frame.
+ *
+ * This function is used by the linux-fb port to implement managed
+ * windows, but it could conceivably be used by X-programs that
+ * want to do their own window decorations.
+ *
+ * Deprecated: 2.24: This function will be removed in GTK+ 3
+ **/</input>
+  <parser>
+<docblock>
+      <identifier>
+        <name>gtk_window_set_has_frame</name>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>window</name>
+          <description>a #GtkWindow</description>
+        </parameter>
+        <parameter>
+          <name>setting</name>
+          <description>(Note: this is a special-purpose function for the framebuffer port,
+ that causes GTK+ to draw its own window border. For most applications,
+ you want gtk_window_set_decorated() instead, which tells the window
+ manager whether to draw the window border.)</description>
+        </parameter>
+      </parameters>
+      <description>If this function is called on a window with setting of %TRUE, before
+it is realized or showed, it will have a "frame" window around
+@window->window, accessible in @window->frame. Using the signal
+frame_event you can receive all events targeted at the frame.
+
+This function is used by the linux-fb port to implement managed
+windows, but it could conceivably be used by X-programs that
+want to do their own window decorations.</description>
+      <tags>
+        <tag>
+          <name>deprecated</name>
+          <value>2.24</value>
+          <description>This function will be removed in GTK+ 3</description>
+        </tag>
+      </tags>
+    </docblock>
+    <messages>
+      <message>5: Error: Test: unbalanced parentheses, annotations will be ignored:
+ * (Note: this is a special-purpose function for the framebuffer port,
+                                                                     ^</message>
+    </messages>
+  </parser>
+  <output>/**
+ * gtk_window_set_has_frame:
+ * @window: a #GtkWindow
+ * @setting: (Note: this is a special-purpose function for the framebuffer port,
+ *  that causes GTK+ to draw its own window border. For most applications,
+ *  you want gtk_window_set_decorated() instead, which tells the window
+ *  manager whether to draw the window border.)
+ *
+ * If this function is called on a window with setting of %TRUE, before
+ * it is realized or showed, it will have a "frame" window around
+ * @window->window, accessible in @window->frame. Using the signal
+ * frame_event you can receive all events targeted at the frame.
+ *
+ * This function is used by the linux-fb port to implement managed
+ * windows, but it could conceivably be used by X-programs that
+ * want to do their own window decorations.
+ *
+ * Deprecated: 2.24: This function will be removed in GTK+ 3
  */</output>
 </test>
 
diff --git a/tests/scanner/annotationparser/gi/tag.xml b/tests/scanner/annotationparser/gi/tag.xml
index 8480d4b4..7dd7bb19 100644
--- a/tests/scanner/annotationparser/gi/tag.xml
+++ b/tests/scanner/annotationparser/gi/tag.xml
@@ -187,25 +187,26 @@ Moo: anything</description>
             <annotation>
               <name>allow-none</name>
             </annotation>
+            <annotation>
+              <name>transfer</name>
+              <options>
+                <option>
+                  <name>full</name>
+                </option>
+              </options>
+            </annotation>
           </annotations>
-          <description>
-(transfer full): something</description>
+          <description>something</description>
         </tag>
       </tags>
     </docblock>
-    <messages>
-      <message>7: Error: Test: ignoring invalid multiline annotation continuation:
- * (transfer full): something
-   ^</message>
-    </messages>
   </parser>
   <output>/**
  * test_multiline_annotations_on_tag:
  *
  * Annotations spanning multiple lines are not valid
  *
- * Returns: (allow-none):
- * (transfer full): something
+ * Returns: (allow-none) (transfer full): something
  */</output>
 </test>