giscanner: deprecate GObject-Introspection GTK-Doc tags

After discussing a different issue with the GTK-Doc maintainers,
we learned that our g-i specific top level tags should never have
existed in the first place. The prefered notation for annotations
that apply to the identifier should be written on the identifier
line, for example like what we already do with (skip).

As a result, this patch deprecates g-i specific top level tags and
implements them as annotations on the identifier instead but still
keeps support for malformed comment blocks using g-i specific top
level tags.

This means that all annotated code "out there" will continue to work
just fine with this version of g-i, but when a developer decides to
fix deprecation warnings in his/her comment blocks, the dependency
on g-i needs to be raised to a version that contains at least this
patch. #676133

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

9 files changed, 941 insertions, 69 deletions

diff --git a/tests/scanner/annotationparser/gi/annotation_get_value_func.xml b/tests/scanner/annotationparser/gi/annotation_get_value_func.xml
index cfc64281..7d1551f7 100644
--- a/tests/scanner/annotationparser/gi/annotation_get_value_func.xml
+++ b/tests/scanner/annotationparser/gi/annotation_get_value_func.xml
@@ -3,8 +3,34 @@
 <tests xmlns="http://schemas.gnome.org/gobject-introspection/2013/test">
 
 <test>
+  <input>/**
+ * RegressTestFundamentalObject: (get-value-func regress_test_value_get_fundamental_object)
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>get-value-func</name>
+            <options>
+              <option>
+                <name>regress_test_value_get_fundamental_object</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+  </parser>
+</test>
+
+<test>
   <!--
-  "Get value func:" tag syntax
+  Deprecated "Get value func:" tag syntax
   -->
   <input>/**
  * RegressTestFundamentalObject:
@@ -17,15 +43,91 @@
     <docblock>
       <identifier>
         <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>get-value-func</name>
+            <options>
+              <option>
+                <name>regress_test_value_get_fundamental_object</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+    <messages>
+      <message>6: Warning: Test: GObject-Introspection specific GTK-Doc tag "Get value func" has been deprecated, please use annotations on the identifier instead:
+ * Get value func: regress_test_value_get_fundamental_object
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Get value func:" tag syntax in the wrong location
+  -->
+  <input>/**
+ * RegressTestFundamentalObject:
+ *
+ * Get value func: regress_test_value_get_fundamental_object
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>get-value-func</name>
+            <options>
+              <option>
+                <name>regress_test_value_get_fundamental_object</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: GObject-Introspection specific GTK-Doc tag "Get value func" has been deprecated, please use annotations on the identifier instead:
+ * Get value func: regress_test_value_get_fundamental_object
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <input>/**
+ * RegressTestFundamentalObject: (get-value-func regress_test_value_get_fundamental_object=invalid)
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>get-value-func</name>
+            <options>
+              <option>
+                <name>regress_test_value_get_fundamental_object=invalid</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
       </identifier>
       <description>This object tests regressions...</description>
-      <tags>
-        <tag>
-          <name>get value func</name>
-          <value>regress_test_value_get_fundamental_object</value>
-        </tag>
-      </tags>
     </docblock>
+    <messages>
+      <message>2: Warning: Test: invalid annotation options: expected a "list" but received "key=value pairs":
+ * RegressTestFundamentalObject: (get-value-func regress_test_value_get_fundamental_object=invalid)
+                                                                                          ^</message>
+    </messages>
   </parser>
 </test>
 
diff --git a/tests/scanner/annotationparser/gi/annotation_ref_func.xml b/tests/scanner/annotationparser/gi/annotation_ref_func.xml
index 5f945701..c97683b2 100644
--- a/tests/scanner/annotationparser/gi/annotation_ref_func.xml
+++ b/tests/scanner/annotationparser/gi/annotation_ref_func.xml
@@ -3,8 +3,34 @@
 <tests xmlns="http://schemas.gnome.org/gobject-introspection/2013/test">
 
 <test>
+  <input>/**
+ * RegressTestFundamentalObject: (ref-func regress_test_fundamental_object_ref)
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>ref-func</name>
+            <options>
+              <option>
+                <name>regress_test_fundamental_object_ref</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+  </parser>
+</test>
+
+<test>
   <!--
-  "Ref func:" tag syntax
+  Deprecated "Ref func:" tag syntax
   -->
   <input>/**
  * RegressTestFundamentalObject:
@@ -17,15 +43,91 @@
     <docblock>
       <identifier>
         <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>ref-func</name>
+            <options>
+              <option>
+                <name>regress_test_fundamental_object_ref</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+    <messages>
+      <message>6: Warning: Test: GObject-Introspection specific GTK-Doc tag "Ref func" has been deprecated, please use annotations on the identifier instead:
+ * Ref func: regress_test_fundamental_object_ref
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Ref func:" tag syntax in the wrong location
+  -->
+  <input>/**
+ * RegressTestFundamentalObject:
+ *
+ * Ref func: regress_test_fundamental_object_ref
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>ref-func</name>
+            <options>
+              <option>
+                <name>regress_test_fundamental_object_ref</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: GObject-Introspection specific GTK-Doc tag "Ref func" has been deprecated, please use annotations on the identifier instead:
+ * Ref func: regress_test_fundamental_object_ref
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <input>/**
+ * RegressTestFundamentalObject: (ref-func regress_test_fundamental_object_ref=invalid)
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>ref-func</name>
+            <options>
+              <option>
+                <name>regress_test_fundamental_object_ref=invalid</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
       </identifier>
       <description>This object tests regressions...</description>
-      <tags>
-        <tag>
-          <name>ref func</name>
-          <value>regress_test_fundamental_object_ref</value>
-        </tag>
-      </tags>
     </docblock>
+    <messages>
+      <message>2: Warning: Test: invalid annotation options: expected a "list" but received "key=value pairs":
+ * RegressTestFundamentalObject: (ref-func regress_test_fundamental_object_ref=invalid)
+                                                                              ^</message>
+    </messages>
   </parser>
 </test>
 
diff --git a/tests/scanner/annotationparser/gi/annotation_rename_to.xml b/tests/scanner/annotationparser/gi/annotation_rename_to.xml
index 5d9d3b1b..9fecdaf5 100644
--- a/tests/scanner/annotationparser/gi/annotation_rename_to.xml
+++ b/tests/scanner/annotationparser/gi/annotation_rename_to.xml
@@ -3,8 +3,56 @@
 <tests xmlns="http://schemas.gnome.org/gobject-introspection/2013/test">
 
 <test>
+  <input>/**
+ * annotation_object_watch_full: (rename-to annotation_object_watch)
+ * @object: A #AnnotationObject
+ * @func: The callback
+ * @user_data: The callback data
+ * @destroy: Destroy notification
+ *
+ * Test overriding via the "Rename To" annotation.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>annotation_object_watch_full</name>
+        <annotations>
+          <annotation>
+            <name>rename-to</name>
+            <options>
+              <option>
+                <name>annotation_object_watch</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>object</name>
+          <description>A #AnnotationObject</description>
+        </parameter>
+        <parameter>
+          <name>func</name>
+          <description>The callback</description>
+        </parameter>
+        <parameter>
+          <name>user_data</name>
+          <description>The callback data</description>
+        </parameter>
+        <parameter>
+          <name>destroy</name>
+          <description>Destroy notification</description>
+        </parameter>
+      </parameters>
+      <description>Test overriding via the "Rename To" annotation.</description>
+    </docblock>
+  </parser>
+</test>
+
+<test>
   <!--
-  "Rename to:" tag syntax
+  Deprecated "Rename to:" tag syntax
   -->
   <input>/**
  * annotation_object_watch_full:
@@ -21,6 +69,105 @@
     <docblock>
       <identifier>
         <name>annotation_object_watch_full</name>
+        <annotations>
+          <annotation>
+            <name>rename-to</name>
+            <options>
+              <option>
+                <name>annotation_object_watch</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>object</name>
+          <description>A #AnnotationObject</description>
+        </parameter>
+        <parameter>
+          <name>func</name>
+          <description>The callback</description>
+        </parameter>
+        <parameter>
+          <name>user_data</name>
+          <description>The callback data</description>
+        </parameter>
+        <parameter>
+          <name>destroy</name>
+          <description>Destroy notification</description>
+        </parameter>
+      </parameters>
+      <description>Test overriding via the "Rename To" annotation.</description>
+    </docblock>
+    <messages>
+      <message>10: Warning: Test: GObject-Introspection specific GTK-Doc tag "Rename to" has been deprecated, please use annotations on the identifier instead:
+ * Rename to: annotation_object_watch
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Rename to:" tag syntax in the wrong location
+  -->
+  <input>/**
+ * annotation_object_watch_full:
+ *
+ * Rename to: annotation_object_watch
+ *
+ * Test overriding via the "Rename To" annotation.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>annotation_object_watch_full</name>
+        <annotations>
+          <annotation>
+            <name>rename-to</name>
+            <options>
+              <option>
+                <name>annotation_object_watch</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>Test overriding via the "Rename To" annotation.</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: GObject-Introspection specific GTK-Doc tag "Rename to" has been deprecated, please use annotations on the identifier instead:
+ * Rename to: annotation_object_watch
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <input>/**
+ * annotation_object_watch_full: (rename-to annotation_object_watch=invalid)
+ * @object: A #AnnotationObject
+ * @func: The callback
+ * @user_data: The callback data
+ * @destroy: Destroy notification
+ *
+ * Test overriding via the "Rename To" annotation.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>annotation_object_watch_full</name>
+        <annotations>
+          <annotation>
+            <name>rename-to</name>
+            <options>
+              <option>
+                <name>annotation_object_watch=invalid</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
       </identifier>
       <parameters>
         <parameter>
@@ -41,13 +188,12 @@
         </parameter>
       </parameters>
       <description>Test overriding via the "Rename To" annotation.</description>
-      <tags>
-        <tag>
-          <name>rename to</name>
-          <value>annotation_object_watch</value>
-        </tag>
-      </tags>
     </docblock>
+    <messages>
+      <message>2: Warning: Test: invalid annotation options: expected a "list" but received "key=value pairs":
+ * annotation_object_watch_full: (rename-to annotation_object_watch=invalid)
+                                                                   ^</message>
+    </messages>
   </parser>
 </test>
 
diff --git a/tests/scanner/annotationparser/gi/annotation_set_value_func.xml b/tests/scanner/annotationparser/gi/annotation_set_value_func.xml
index 0164a5b8..4619fb9f 100644
--- a/tests/scanner/annotationparser/gi/annotation_set_value_func.xml
+++ b/tests/scanner/annotationparser/gi/annotation_set_value_func.xml
@@ -3,8 +3,34 @@
 <tests xmlns="http://schemas.gnome.org/gobject-introspection/2013/test">
 
 <test>
+  <input>/**
+ * RegressTestFundamentalObject: (set-value-func regress_test_value_set_fundamental_object)
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>set-value-func</name>
+            <options>
+              <option>
+                <name>regress_test_value_set_fundamental_object</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+  </parser>
+</test>
+
+<test>
   <!--
-  "Set value func:" tag syntax
+  Deprecated "Set value func:" tag syntax
   -->
   <input>/**
  * RegressTestFundamentalObject:
@@ -17,15 +43,60 @@
     <docblock>
       <identifier>
         <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>set-value-func</name>
+            <options>
+              <option>
+                <name>regress_test_value_set_fundamental_object</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
       </identifier>
       <description>This object tests regressions...</description>
-      <tags>
-        <tag>
-          <name>set value func</name>
-          <value>regress_test_value_set_fundamental_object</value>
-        </tag>
-      </tags>
     </docblock>
+    <messages>
+      <message>6: Warning: Test: GObject-Introspection specific GTK-Doc tag "Set value func" has been deprecated, please use annotations on the identifier instead:
+ * Set value func: regress_test_value_set_fundamental_object
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Set value func:" tag syntax in the wrong location
+  -->
+  <input>/**
+ * RegressTestFundamentalObject:
+ *
+ * Set value func: regress_test_value_set_fundamental_object
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>set-value-func</name>
+            <options>
+              <option>
+                <name>regress_test_value_set_fundamental_object</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: GObject-Introspection specific GTK-Doc tag "Set value func" has been deprecated, please use annotations on the identifier instead:
+ * Set value func: regress_test_value_set_fundamental_object
+   ^</message>
+    </messages>
   </parser>
 </test>
 
diff --git a/tests/scanner/annotationparser/gi/annotation_transfer.xml b/tests/scanner/annotationparser/gi/annotation_transfer.xml
index 535a4d28..3bbb8c49 100644
--- a/tests/scanner/annotationparser/gi/annotation_transfer.xml
+++ b/tests/scanner/annotationparser/gi/annotation_transfer.xml
@@ -139,8 +139,36 @@ known by GObject as it's only marked as G_TYPE_POINTER</description>
 </test>
 
 <test>
+  <input>/**
+ * FsSession:codecs-without-config: (transfer full)
+ *
+ * This is the same list of codecs as #FsSession:codecs
+ * without....
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>FsSession:codecs-without-config</name>
+        <annotations>
+          <annotation>
+            <name>transfer</name>
+            <options>
+              <option>
+                <name>full</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This is the same list of codecs as #FsSession:codecs
+without....</description>
+    </docblock>
+  </parser>
+</test>
+
+<test>
   <!--
-  "Transfer:" tag syntax
+  Deprecated "Transfer:" tag syntax
   -->
   <input>/**
  * FsSession:codecs-without-config:
@@ -154,16 +182,63 @@ known by GObject as it's only marked as G_TYPE_POINTER</description>
     <docblock>
       <identifier>
         <name>FsSession:codecs-without-config</name>
+        <annotations>
+          <annotation>
+            <name>transfer</name>
+            <options>
+              <option>
+                <name>full</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
       </identifier>
       <description>This is the same list of codecs as #FsSession:codecs
 without....</description>
-      <tags>
-        <tag>
-          <name>transfer</name>
-          <value>full</value>
-        </tag>
-      </tags>
     </docblock>
+    <messages>
+      <message>7: Warning: Test: GObject-Introspection specific GTK-Doc tag "Transfer" has been deprecated, please use annotations on the identifier instead:
+ * Transfer: full
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Transfer:" tag syntax in the wrong location
+  -->
+  <input>/**
+ * FsSession:codecs-without-config:
+ *
+ * Transfer: full
+ *
+ * This is the same list of codecs as #FsSession:codecs
+ * without....
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>FsSession:codecs-without-config</name>
+        <annotations>
+          <annotation>
+            <name>transfer</name>
+            <options>
+              <option>
+                <name>full</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This is the same list of codecs as #FsSession:codecs
+without....</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: GObject-Introspection specific GTK-Doc tag "Transfer" has been deprecated, please use annotations on the identifier instead:
+ * Transfer: full
+   ^</message>
+    </messages>
   </parser>
 </test>
 
diff --git a/tests/scanner/annotationparser/gi/annotation_type.xml b/tests/scanner/annotationparser/gi/annotation_type.xml
index 885b4bcc..f2e35d4b 100644
--- a/tests/scanner/annotationparser/gi/annotation_type.xml
+++ b/tests/scanner/annotationparser/gi/annotation_type.xml
@@ -59,29 +59,175 @@ known by GObject as it's only marked as G_TYPE_POINTER</description>
 </test>
 
 <test>
+  <input>/**
+ * AnnotationObject:hash-table: (type GLib.HashTable(utf8,gint8)) (transfer container)
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>AnnotationObject:hash-table</name>
+        <annotations>
+          <annotation>
+            <name>type</name>
+            <options>
+              <option>
+                <name>GLib.HashTable(utf8,gint8)</name>
+              </option>
+            </options>
+          </annotation>
+          <annotation>
+            <name>transfer</name>
+            <options>
+              <option>
+                <name>container</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+    </docblock>
+  </parser>
+</test>
+
+<test>
   <!--
-  "Type:" tag syntax
+  Deprecated inequality sign/angled brackets notation.
+  -->
+  <input><![CDATA[/**
+ * AnnotationObject:hash-table: (type GLib.HashTable<utf8,gint8>) (transfer container)
+ */]]></input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>AnnotationObject:hash-table</name>
+        <annotations>
+          <annotation>
+            <name>type</name>
+            <options>
+              <option>
+                <name>GLib.HashTable(utf8,gint8)</name>
+              </option>
+            </options>
+          </annotation>
+          <annotation>
+            <name>transfer</name>
+            <options>
+              <option>
+                <name>container</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+    </docblock>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Type:" tag syntax
   -->
   <input>/**
-   * RegressTestObj:hash-table:
-   *
-   * Test.
-   *
-   * Type: GLib.HashTable(utf8,gint8)
-   */</input>
+ * RegressTestObj:hash-table:
+ *
+ * Test.
+ *
+ * Type: GLib.HashTable(utf8,gint8)
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestObj:hash-table</name>
+        <annotations>
+          <annotation>
+            <name>type</name>
+            <options>
+              <option>
+                <name>GLib.HashTable(utf8,gint8)</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>Test.</description>
+    </docblock>
+    <messages>
+      <message>6: Warning: Test: GObject-Introspection specific GTK-Doc tag "Type" has been deprecated, please use annotations on the identifier instead:
+ * Type: GLib.HashTable(utf8,gint8)
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Type:" tag syntax in the wrong location
+  -->
+  <input>/**
+ * RegressTestObj:hash-table:
+ *
+ * Type: GLib.HashTable(utf8,gint8)
+ *
+ * Test.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestObj:hash-table</name>
+        <annotations>
+          <annotation>
+            <name>type</name>
+            <options>
+              <option>
+                <name>GLib.HashTable(utf8,gint8)</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>Test.</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: GObject-Introspection specific GTK-Doc tag "Type" has been deprecated, please use annotations on the identifier instead:
+ * Type: GLib.HashTable(utf8,gint8)
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated angled brackets in deprecated "Type:" tag syntax
+  -->
+  <input><![CDATA[/**
+ * RegressTestObj:hash-table:
+ *
+ * Test.
+ *
+ * Type: GLib.HashTable<utf8,gint8>
+ */]]></input>
   <parser>
     <docblock>
       <identifier>
         <name>RegressTestObj:hash-table</name>
+        <annotations>
+          <annotation>
+            <name>type</name>
+            <options>
+              <option>
+                <name>GLib.HashTable(utf8,gint8)</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
       </identifier>
       <description>Test.</description>
-      <tags>
-        <tag>
-          <name>type</name>
-          <value>GLib.HashTable(utf8,gint8)</value>
-        </tag>
-      </tags>
     </docblock>
+    <messages>
+      <message><![CDATA[6: Warning: Test: GObject-Introspection specific GTK-Doc tag "Type" has been deprecated, please use annotations on the identifier instead:
+ * Type: GLib.HashTable<utf8,gint8>
+   ^]]></message>
+    </messages>
   </parser>
 </test>
 
diff --git a/tests/scanner/annotationparser/gi/annotation_unref_func.xml b/tests/scanner/annotationparser/gi/annotation_unref_func.xml
index 528923b2..a8a911c4 100644
--- a/tests/scanner/annotationparser/gi/annotation_unref_func.xml
+++ b/tests/scanner/annotationparser/gi/annotation_unref_func.xml
@@ -3,8 +3,34 @@
 <tests xmlns="http://schemas.gnome.org/gobject-introspection/2013/test">
 
 <test>
+  <input>/**
+ * RegressTestFundamentalObject: (unref-func regress_test_fundamental_object_unref)
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>unref-func</name>
+            <options>
+              <option>
+                <name>regress_test_fundamental_object_unref</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+  </parser>
+</test>
+
+<test>
   <!--
-  "Unref func:" tag syntax
+  Deprecated "Unref func:" tag syntax
   -->
   <input>/**
  * RegressTestFundamentalObject:
@@ -17,15 +43,60 @@
     <docblock>
       <identifier>
         <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>unref-func</name>
+            <options>
+              <option>
+                <name>regress_test_fundamental_object_unref</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
       </identifier>
       <description>This object tests regressions...</description>
-      <tags>
-        <tag>
-          <name>unref func</name>
-          <value>regress_test_fundamental_object_unref</value>
-        </tag>
-      </tags>
     </docblock>
+    <messages>
+      <message>6: Warning: Test: GObject-Introspection specific GTK-Doc tag "Unref func" has been deprecated, please use annotations on the identifier instead:
+ * Unref func: regress_test_fundamental_object_unref
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Unref func:" tag syntax in the wrong location
+  -->
+  <input>/**
+ * RegressTestFundamentalObject:
+ *
+ * Unref func: regress_test_fundamental_object_unref
+ *
+ * This object tests regressions...
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>RegressTestFundamentalObject</name>
+        <annotations>
+          <annotation>
+            <name>unref-func</name>
+            <options>
+              <option>
+                <name>regress_test_fundamental_object_unref</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>This object tests regressions...</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: GObject-Introspection specific GTK-Doc tag "Unref func" has been deprecated, please use annotations on the identifier instead:
+ * Unref func: regress_test_fundamental_object_unref
+   ^</message>
+    </messages>
   </parser>
 </test>
 
diff --git a/tests/scanner/annotationparser/gi/annotation_value.xml b/tests/scanner/annotationparser/gi/annotation_value.xml
index c5acb4ed..06f2bf2c 100644
--- a/tests/scanner/annotationparser/gi/annotation_value.xml
+++ b/tests/scanner/annotationparser/gi/annotation_value.xml
@@ -3,8 +3,34 @@
 <tests xmlns="http://schemas.gnome.org/gobject-introspection/2013/test">
 
 <test>
+  <input>/**
+ * ANNOTATION_CALCULATED_LARGE: (value 10000000000UL)
+ *
+ * Constant to define a calculated large value
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>ANNOTATION_CALCULATED_LARGE</name>
+        <annotations>
+          <annotation>
+            <name>value</name>
+            <options>
+              <option>
+                <name>10000000000UL</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>Constant to define a calculated large value</description>
+    </docblock>
+  </parser>
+</test>
+
+<test>
   <!--
-  "Value:" tag syntax
+  Deprecated "Value:" tag syntax
   -->
   <input>/**
  * ANNOTATION_CALCULATED_LARGE:
@@ -17,15 +43,60 @@
     <docblock>
       <identifier>
         <name>ANNOTATION_CALCULATED_LARGE</name>
+        <annotations>
+          <annotation>
+            <name>value</name>
+            <options>
+              <option>
+                <name>10000000000UL</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
       </identifier>
       <description>Constant to define a calculated large value</description>
-      <tags>
-        <tag>
-         <name>value</name>
-         <value>10000000000UL</value>
-        </tag>
-      </tags>
     </docblock>
+    <messages>
+      <message>6: Warning: Test: GObject-Introspection specific GTK-Doc tag "Value" has been deprecated, please use annotations on the identifier instead:
+ * Value: 10000000000UL
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Value:" tag syntax in the wrong location
+  -->
+  <input>/**
+ * ANNOTATION_CALCULATED_LARGE:
+ *
+ * Value: 10000000000UL
+ *
+ * Constant to define a calculated large value
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>ANNOTATION_CALCULATED_LARGE</name>
+        <annotations>
+          <annotation>
+            <name>value</name>
+            <options>
+              <option>
+                <name>10000000000UL</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>Constant to define a calculated large value</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: GObject-Introspection specific GTK-Doc tag "Value" has been deprecated, please use annotations on the identifier instead:
+ * Value: 10000000000UL
+   ^</message>
+    </messages>
   </parser>
 </test>
 
diff --git a/tests/scanner/annotationparser/gi/annotation_virtual.xml b/tests/scanner/annotationparser/gi/annotation_virtual.xml
index e01d9933..7439a699 100644
--- a/tests/scanner/annotationparser/gi/annotation_virtual.xml
+++ b/tests/scanner/annotationparser/gi/annotation_virtual.xml
@@ -3,8 +3,51 @@
 <tests xmlns="http://schemas.gnome.org/gobject-introspection/2013/test">
 
 <test>
+  <input>/**
+ * foo_object_read: (virtual read_fn)
+ * @object: obj
+ * @offset: offset
+ * @length: length
+ *
+ * Read some stuff.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>foo_object_read</name>
+        <annotations>
+          <annotation>
+            <name>virtual</name>
+            <options>
+              <option>
+                <name>read_fn</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <parameters>
+        <parameter>
+          <name>object</name>
+          <description>obj</description>
+        </parameter>
+        <parameter>
+          <name>offset</name>
+          <description>offset</description>
+        </parameter>
+        <parameter>
+          <name>length</name>
+          <description>length</description>
+        </parameter>
+      </parameters>
+      <description>Read some stuff.</description>
+    </docblock>
+  </parser>
+</test>
+
+<test>
   <!--
-  "Virtual:" tag syntax
+  Deprecated "Virtual:" tag syntax
   -->
   <input>/**
  * foo_object_read:
@@ -20,6 +63,16 @@
     <docblock>
       <identifier>
         <name>foo_object_read</name>
+        <annotations>
+          <annotation>
+            <name>virtual</name>
+            <options>
+              <option>
+                <name>read_fn</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
       </identifier>
       <parameters>
         <parameter>
@@ -36,13 +89,48 @@
         </parameter>
       </parameters>
       <description>Read some stuff.</description>
-      <tags>
-        <tag>
-          <name>virtual</name>
-          <value>read_fn</value>
-        </tag>
-      </tags>
     </docblock>
+    <messages>
+      <message>9: Warning: Test: GObject-Introspection specific GTK-Doc tag "Virtual" has been deprecated, please use annotations on the identifier instead:
+ * Virtual: read_fn
+   ^</message>
+    </messages>
+  </parser>
+</test>
+
+<test>
+  <!--
+  Deprecated "Virtual:" tag syntax in the wrong location
+  -->
+  <input>/**
+ * foo_object_read:
+ *
+ * Virtual: read_fn
+ *
+ * Read some stuff.
+ */</input>
+  <parser>
+    <docblock>
+      <identifier>
+        <name>foo_object_read</name>
+        <annotations>
+          <annotation>
+            <name>virtual</name>
+            <options>
+              <option>
+                <name>read_fn</name>
+              </option>
+            </options>
+          </annotation>
+        </annotations>
+      </identifier>
+      <description>Read some stuff.</description>
+    </docblock>
+    <messages>
+      <message>4: Warning: Test: GObject-Introspection specific GTK-Doc tag "Virtual" has been deprecated, please use annotations on the identifier instead:
+ * Virtual: read_fn
+   ^</message>
+    </messages>
   </parser>
 </test>