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

14 files changed, 954 insertions, 116 deletions

diff --git a/tests/gimarshallingtests.c b/tests/gimarshallingtests.c
index 05502951..02c33de2 100644
--- a/tests/gimarshallingtests.c
+++ b/tests/gimarshallingtests.c
@@ -4114,11 +4114,9 @@ static void
 }
 
 /**
- * gi_marshalling_tests_object_vfunc_with_callback:
+ * gi_marshalling_tests_object_vfunc_with_callback: (virtual vfunc_with_callback)
  * @callback: (scope call) (closure callback_data):
  * @callback_data: (allow-none):
- *
- * Virtual: vfunc_with_callback
  */
 void
 gi_marshalling_tests_object_vfunc_with_callback (GIMarshallingTestsObject *
@@ -5312,10 +5310,7 @@ static void gi_marshalling_tests_properties_object_class_init (GIMarshallingTest
                                                        (), G_PARAM_READABLE | G_PARAM_WRITABLE | G_PARAM_CONSTRUCT));
 
     /**
-     * GIMarshallingTestsPropertiesObject:some-boxed-glist:
-     *
-     * Type: GLib.List(gint)
-     * Transfer: none
+     * GIMarshallingTestsPropertiesObject:some-boxed-glist: (type GLib.List(gint)) (transfer none):
      */
   g_object_class_install_property (object_class, SOME_BOXED_GLIST_PROPERTY,
                                    g_param_spec_boxed ("some-boxed-glist",
diff --git a/tests/scanner/annotation.c b/tests/scanner/annotation.c
index 32187d38..30dc72ef 100644
--- a/tests/scanner/annotation.c
+++ b/tests/scanner/annotation.c
@@ -163,9 +163,7 @@ regress_annotation_object_class_init (RegressAnnotationObjectClass *klass)
                                                         NULL,
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
   /**
-   * RegressAnnotationObject:function-property:
-   *
-   * Type: RegressAnnotationCallback
+   * RegressAnnotationObject:function-property: (type RegressAnnotationCallback)
    */
   g_object_class_install_property (gobject_class,
                                    PROP_FUNCTION_PROPERTY,
@@ -616,15 +614,13 @@ regress_annotation_object_watch (RegressAnnotationObject *object,
 }
 
 /**
- * regress_annotation_object_watch_full:
+ * regress_annotation_object_watch_full: (rename-to regress_annotation_object_watch)
  * @object: A #RegressAnnotationObject
  * @func: The callback
  * @user_data: The callback data
  * @destroy: Destroy notification
  *
  * Test overriding via the "Rename To" annotation.
- *
- * Rename to: regress_annotation_object_watch
  */
 void
 regress_annotation_object_watch_full (RegressAnnotationObject *object,
diff --git a/tests/scanner/annotation.h b/tests/scanner/annotation.h
index b982a5b7..2084da29 100644
--- a/tests/scanner/annotation.h
+++ b/tests/scanner/annotation.h
@@ -173,22 +173,18 @@ GObject * regress_annotation_transfer_floating(void);
 #define REGRESS_ANNOTATION_CALCULATED_DEFINE (10 * 10)
 
 /**
- * REGRESS_ANNOTATION_CALCULATED_LARGE:
+ * REGRESS_ANNOTATION_CALCULATED_LARGE: (value 10000000000UL)
  *
  * Constant to define a calculated large value
  *
- * Value: 10000000000UL
- *
  * Since: 1.4
  */
 #define REGRESS_ANNOTATION_CALCULATED_LARGE (1000 * G_GINT64_CONSTANT (10000000))
 
 /**
- * REGRESS_ANNOTATION_CALCULATED_LARGE_DIV:
+ * REGRESS_ANNOTATION_CALCULATED_LARGE_DIV: (value 1000000UL)
  *
  * Constant to define a calculated large value
- *
- * Value: 1000000UL
  */
 #define REGRESS_ANNOTATION_CALCULATED_LARGE_DIV (1000 / G_GINT64_CONSTANT (10000000))
 
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>
 
diff --git a/tests/scanner/foo.c b/tests/scanner/foo.c
index 4d5090b6..52b9054e 100644
--- a/tests/scanner/foo.c
+++ b/tests/scanner/foo.c
@@ -285,14 +285,12 @@ regress_foo_object_dup_name (RegressFooObject *object)
 }
 
 /**
- * regress_foo_object_read:
+ * regress_foo_object_read: (virtual read_fn)
  * @object: obj
  * @offset: offset
  * @length: length
  *
  * Read some stuff.
- *
- * Virtual: read_fn
  */
 void
 regress_foo_object_read (RegressFooObject *object, int offset, int length)
diff --git a/tests/scanner/regress.c b/tests/scanner/regress.c
index d32c52be..aa9f83a8 100644
--- a/tests/scanner/regress.c
+++ b/tests/scanner/regress.c
@@ -2455,10 +2455,7 @@ regress_test_obj_class_init (RegressTestObjClass *klass)
                                    pspec);
 
   /**
-   * RegressTestObj:hash-table:
-   *
-   * Type: GLib.HashTable(utf8,gint8)
-   * Transfer: container
+   * RegressTestObj:hash-table: (type GLib.HashTable(utf8,gint8)) (transfer container)
    */
   pspec = g_param_spec_boxed ("hash-table",
                               "GHashTable property",
@@ -2470,10 +2467,7 @@ regress_test_obj_class_init (RegressTestObjClass *klass)
                                    pspec);
 
   /**
-   * RegressTestObj:list:
-   *
-   * Type: GLib.List(utf8)
-   * Transfer: none
+   * RegressTestObj:list: (type GLib.List(utf8)) (transfer none)
    */
   pspec = g_param_spec_pointer ("list",
                                 "GList property",
@@ -2484,10 +2478,7 @@ regress_test_obj_class_init (RegressTestObjClass *klass)
                                    pspec);
 
   /**
-   * RegressTestObj:hash-table-old:
-   *
-   * Type: GLib.HashTable<utf8,gint8>
-   * Transfer: container
+   * RegressTestObj:hash-table-old: (type GLib.HashTable<utf8,gint8>) (transfer container)
    */
   pspec = g_param_spec_boxed ("hash-table-old",
                               "GHashTable property with <>",
@@ -2499,10 +2490,7 @@ regress_test_obj_class_init (RegressTestObjClass *klass)
                                    pspec);
 
   /**
-   * RegressTestObj:list-old:
-   *
-   * Type: GLib.List<utf8>
-   * Transfer: none
+   * RegressTestObj:list-old: (type GLib.List<utf8>) (transfer none)
    */
   pspec = g_param_spec_pointer ("list-old",
                                 "GList property with ()",
@@ -2923,15 +2911,13 @@ regress_test_obj_skip_inout_param (RegressTestObj *obj,
 }
 
 /**
- * regress_test_obj_do_matrix:
+ * regress_test_obj_do_matrix: (virtual matrix)
  * @obj: A #RegressTestObj
  * @somestr: Meaningless string
  *
  * This method is virtual.  Notably its name differs from the virtual
  * slot name, which makes it useful for testing bindings handle this
  * case.
- *
- * Virtual: matrix
  */
 int
 regress_test_obj_do_matrix (RegressTestObj *obj, const char *somestr)
@@ -3181,12 +3167,7 @@ regress_test_fundamental_object_init (GTypeInstance * instance, gpointer klass)
 }
 
 /**
- * RegressTestFundamentalObject:
- *
- * Ref Func: regress_test_fundamental_object_ref
- * Unref Func: regress_test_fundamental_object_unref
- * Set Value Func: regress_test_value_set_fundamental_object
- * Get Value Func: regress_test_value_get_fundamental_object
+ * RegressTestFundamentalObject: (ref-func regress_test_fundamental_object_ref) (unref-func regress_test_fundamental_object_unref) (set-value-func regress_test_value_set_fundamental_object) (get-value-func regress_test_value_get_fundamental_object)
  */
 
 GType