From d7504419093aef9fae802ad599cff1bf9022e24d Mon Sep 17 00:00:00 2001
From: Mathieu Duponchelle <mathieu@centricular.com>
Date: Wed, 1 Jul 2020 23:34:34 +0200
Subject: giscanner: parse block comments for members and fields

There was previously no mechanism for tagging enum members
and struct fields with Since tags (or other, eg deprecation tags).

While the customary place to add Since tags for these symbols
is inline in the parent symbol's documentation eg:

/**
 * Foo:
 *
 * @FOO_BAR: some bar. Since X.Y
 */

And variations on that theme, implementing parsing for that scheme
would result in a pretty ambiguous grammar, especially if we also
want support for multiple tags.

Instead, the solution implemented here is to allow providing
documentation for individual members and fields through their
own separate block, as is done for virtual functions already.

Inline comments are still used, with a lower precedence.

Fixes #348
---
 giscanner/annotationparser.py                      |  34 ++++-
 giscanner/girwriter.py                             |   2 +
 giscanner/maintransformer.py                       |  49 ++++---
 .../Regress.AnnotationFields-field4.page           |  14 ++
 .../Regress.AnnotationBitfield.page                |   4 +
 .../Regress.AnnotationFields-field4.page           |  18 +++
 .../Regress.AnnotationFields.page                  |   1 +
 .../Regress.AnnotationBitfield.page                |   4 +
 .../Regress.AnnotationFields-field4.page           |  14 ++
 tests/scanner/Regress-1.0-expected.gir             | 159 +++++++++++----------
 tests/scanner/annotation.h                         |  17 ++-
 11 files changed, 221 insertions(+), 95 deletions(-)
 create mode 100644 tests/scanner/Regress-1.0-C-expected/Regress.AnnotationFields-field4.page
 create mode 100644 tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationFields-field4.page
 create mode 100644 tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationFields-field4.page

diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py
index 63212963..f8257206 100644
--- a/giscanner/annotationparser.py
+++ b/giscanner/annotationparser.py
@@ -461,6 +461,27 @@ ACTION_RE = re.compile(
     ''',
     re.UNICODE | re.VERBOSE)
 
+# Pattern matching struct fields.
+FIELD_RE = re.compile(
+    r'''
+    ^                                                    # start
+    \s*                                                  # 0 or more whitespace characters
+    (?P<class_name>[\w]+)                                # class name
+    \s*                                                  # 0 or more whitespace characters
+    \.{1}                                                # 1 required dot
+    \s*                                                  # 0 or more whitespace characters
+    (?P<field_name>[\w-]*\w)                             # field name
+    \s*                                                  # 0 or more whitespace characters
+    (?P<delimiter>:?)                                    # delimiter
+    \s*                                                  # 0 or more whitespace characters
+    (?P<fields>.*?)                                      # annotations + description
+    \s*                                                  # 0 or more whitespace characters
+    :?                                                   # invalid delimiter
+    \s*                                                  # 0 or more whitespace characters
+    $                                                    # end
+    ''',
+    re.UNICODE | re.VERBOSE)
+
 # Pattern matching parameters.
 PARAMETER_RE = re.compile(
     r'''
@@ -1368,13 +1389,22 @@ class GtkDocCommentBlockParser(object):
                                 identifier_fields = None
                                 identifier_fields_start = None
                             else:
-                                result = SYMBOL_RE.match(line)
+                                result = FIELD_RE.match(line)
 
                                 if result:
-                                    identifier_name = '%s' % (result.group('symbol_name'), )
+                                    identifier_name = '%s.%s' % (result.group('class_name'),
+                                                                  result.group('field_name'))
                                     identifier_delimiter = result.group('delimiter')
                                     identifier_fields = result.group('fields')
                                     identifier_fields_start = result.start('fields')
+                                else:
+                                    result = SYMBOL_RE.match(line)
+
+                                    if result:
+                                        identifier_name = '%s' % (result.group('symbol_name'), )
+                                        identifier_delimiter = result.group('delimiter')
+                                        identifier_fields = result.group('fields')
+                                        identifier_fields_start = result.start('fields')
 
                 if result:
                     in_part = PART_IDENTIFIER
diff --git a/giscanner/girwriter.py b/giscanner/girwriter.py
index d1333cb7..41d3ead2 100644
--- a/giscanner/girwriter.py
+++ b/giscanner/girwriter.py
@@ -437,6 +437,7 @@ class GIRWriter(XMLWriter):
         attrs = [('name', member.name),
                  ('value', str(member.value)),
                  ('c:identifier', member.symbol)]
+        self._append_version(member, attrs)
         if member.nick is not None:
             attrs.append(('glib:nick', member.nick))
         with self.tagcontext('member', attrs):
@@ -626,6 +627,7 @@ class GIRWriter(XMLWriter):
                 raise AssertionError("Unknown field anonymous: %r" % (field.anonymous_node, ))
         else:
             attrs = [('name', field.name)]
+            self._append_version(field, attrs)
             self._append_node_generic(field, attrs)
             # Fields are assumed to be read-only
             # (see also girparser.c and generate.c)
diff --git a/giscanner/maintransformer.py b/giscanner/maintransformer.py
index 9468751d..3c4ef695 100644
--- a/giscanner/maintransformer.py
+++ b/giscanner/maintransformer.py
@@ -858,19 +858,28 @@ class MainTransformer(object):
         self._apply_annotations_params(node, node.parameters, block)
         self._apply_annotations_return(node, node.retval, block)
 
-    def _apply_annotations_field(self, parent, block, field):
-        if not block:
-            return
-        tag = block.params.get(field.name)
-        if not tag:
+    def _apply_annotations_field(self, parent, parent_block, field):
+        block = self._blocks.get('%s.%s' % (self._get_annotation_name(parent), field.name))
+
+        # Prioritize block level documentation
+        if block:
+            self._apply_annotations_annotated(field, block)
+            annotations = block.annotations
+        elif not parent_block:
             return
-        type_annotation = tag.annotations.get(ANN_TYPE)
+        else:
+            tag = parent_block.params.get(field.name)
+            if not tag:
+                return
+            annotations = tag.annotations
+            field.doc = tag.description
+            field.doc_position = tag.position
+
+        type_annotation = annotations.get(ANN_TYPE)
         if type_annotation:
             field.type = self._transformer.create_type_from_user_string(type_annotation[0])
-        field.doc = tag.description
-        field.doc_position = tag.position
         try:
-            self._adjust_container_type(parent, field, tag.annotations)
+            self._adjust_container_type(parent, field, annotations)
         except AttributeError as ex:
             print(ex)
 
@@ -938,15 +947,21 @@ class MainTransformer(object):
         if value_annotation:
             node.value = value_annotation[0]
 
-    def _apply_annotations_enum_members(self, node, block):
-        if block is None:
-            return
-
+    def _apply_annotations_enum_members(self, node, parent_block):
         for m in node.members:
-            param = block.params.get(m.symbol, None)
-            if param and param.description:
-                m.doc = param.description
-                m.doc_position = param.position
+            block = self._blocks.get(m.symbol)
+            # Prioritize block-level documentation
+            if block:
+                self._apply_annotations_annotated(m, block)
+            elif parent_block:
+                param = parent_block.params.get(m.symbol)
+
+                if not param:
+                    continue
+
+                if param.description:
+                    m.doc = param.description
+                    m.doc_position = param.position
 
     def _pass_read_annotations2(self, node, chain):
         if isinstance(node, ast.Function):
diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationFields-field4.page b/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationFields-field4.page
new file mode 100644
index 00000000..163d420f
--- /dev/null
+++ b/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationFields-field4.page
@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<page id="Regress.AnnotationFields-field4"
+      type="topic"
+      style="field"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="Regress.AnnotationFields" group="field" type="guide"/>
+  </info>
+  <title>Regress.AnnotationFields->field4</title>
+  <p>A new field, breaking ABI is fun!</p>
+  <p>Since 1.4</p>
+</page>
diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationBitfield.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationBitfield.page
index 355066b2..6f96ddb2 100644
--- a/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationBitfield.page
+++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationBitfield.page
@@ -19,6 +19,10 @@
 <item>
 <title><code>AnnotationBitfield.BAR</code></title>
 
+</item>
+<item>
+<title><code>AnnotationBitfield.FOOBAR</code></title>
+
 </item>
 </terms>
   <links type="topic" ui:expanded="true"
diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationFields-field4.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationFields-field4.page
new file mode 100644
index 00000000..e60c59bc
--- /dev/null
+++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationFields-field4.page
@@ -0,0 +1,18 @@
+<?xml version="1.0"?>
+<page id="Regress.AnnotationFields-field4"
+      type="topic"
+      style="field"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="Regress.AnnotationFields" group="field" type="guide"/>
+    <title type="link" role="topic">field4</title>
+  </info>
+  <title>Regress.AnnotationFields.field4</title>
+  <synopsis><code mime="text/x-gjs">
+AnnotationFields.field4: Number(guint) (Read / Write)
+  </code></synopsis>
+  <p>A new field, breaking ABI is fun!</p>
+  <p>Since 1.4</p>
+</page>
diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationFields.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationFields.page
index 585a97c1..7cd55257 100644
--- a/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationFields.page
+++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationFields.page
@@ -16,6 +16,7 @@ let annotationFields = new Regress.AnnotationFields({
     <link xref='Regress.AnnotationFields-field1'>field1</link>: value
     <link xref='Regress.AnnotationFields-arr'>arr</link>: value
     <link xref='Regress.AnnotationFields-len'>len</link>: value
+    <link xref='Regress.AnnotationFields-field4'>field4</link>: value
 });
   </code></synopsis>
   <p>This is a struct for testing field documentation and annotations</p>
diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationBitfield.page b/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationBitfield.page
index fa303bb4..a9003221 100644
--- a/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationBitfield.page
+++ b/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationBitfield.page
@@ -19,6 +19,10 @@
 <item>
 <title><code>AnnotationBitfield.BAR</code></title>
 
+</item>
+<item>
+<title><code>AnnotationBitfield.FOOBAR</code></title>
+
 </item>
 </terms>
 
diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationFields-field4.page b/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationFields-field4.page
new file mode 100644
index 00000000..163d420f
--- /dev/null
+++ b/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationFields-field4.page
@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<page id="Regress.AnnotationFields-field4"
+      type="topic"
+      style="field"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="Regress.AnnotationFields" group="field" type="guide"/>
+  </info>
+  <title>Regress.AnnotationFields->field4</title>
+  <p>A new field, breaking ABI is fun!</p>
+  <p>Since 1.4</p>
+</page>
diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir
index cef3b124..62f456f8 100644
--- a/tests/scanner/Regress-1.0-expected.gir
+++ b/tests/scanner/Regress-1.0-expected.gir
@@ -58,7 +58,7 @@ and/or use gtk-doc annotations.  -->
     <constant name="ANNOTATION_CALCULATED_DEFINE"
               value="100"
               c:type="REGRESS_ANNOTATION_CALCULATED_DEFINE">
-      <source-position filename="annotation.h" line="282"/>
+      <source-position filename="annotation.h" line="295"/>
       <type name="gint" c:type="gint"/>
     </constant>
     <constant name="ANNOTATION_CALCULATED_LARGE"
@@ -67,8 +67,8 @@ and/or use gtk-doc annotations.  -->
               version="1.4">
       <doc xml:space="preserve"
            filename="annotation.h"
-           line="284">Constant to define a calculated large value</doc>
-      <source-position filename="annotation.h" line="291"/>
+           line="297">Constant to define a calculated large value</doc>
+      <source-position filename="annotation.h" line="304"/>
       <type name="gint" c:type="gint"/>
     </constant>
     <constant name="ANNOTATION_CALCULATED_LARGE_DIV"
@@ -76,8 +76,8 @@ and/or use gtk-doc annotations.  -->
               c:type="REGRESS_ANNOTATION_CALCULATED_LARGE_DIV">
       <doc xml:space="preserve"
            filename="annotation.h"
-           line="293">Constant to define a calculated large value</doc>
-      <source-position filename="annotation.h" line="298"/>
+           line="306">Constant to define a calculated large value</doc>
+      <source-position filename="annotation.h" line="311"/>
       <type name="gint" c:type="gint"/>
     </constant>
     <enumeration name="ATestError"
@@ -112,28 +112,33 @@ and/or use gtk-doc annotations.  -->
       </union>
     </record>
     <bitfield name="AnnotationBitfield" c:type="RegressAnnotationBitfield">
-      <source-position filename="annotation.h" line="12"/>
+      <source-position filename="annotation.h" line="18"/>
       <member name="foo" value="1" c:identifier="ANN_FLAG_FOO">
       </member>
       <member name="bar" value="2" c:identifier="ANN_FLAG_BAR">
       </member>
+      <member name="foobar"
+              value="3"
+              c:identifier="ANN_FLAG_FOOBAR"
+              version="1.4">
+      </member>
     </bitfield>
     <callback name="AnnotationCallback" c:type="RegressAnnotationCallback">
       <doc xml:space="preserve"
            filename="annotation.h"
-           line="14">This is a callback.</doc>
-      <source-position filename="annotation.h" line="21"/>
+           line="20">This is a callback.</doc>
+      <source-position filename="annotation.h" line="27"/>
       <return-value transfer-ownership="none">
         <doc xml:space="preserve"
              filename="annotation.h"
-             line="19">array of ints</doc>
+             line="25">array of ints</doc>
         <type name="gint" c:type="const gint*"/>
       </return-value>
       <parameters>
         <parameter name="in" transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.h"
-               line="16">array of ints</doc>
+               line="22">array of ints</doc>
           <type name="gint" c:type="const gint*"/>
         </parameter>
       </parameters>
@@ -141,18 +146,18 @@ and/or use gtk-doc annotations.  -->
     <record name="AnnotationFields" c:type="RegressAnnotationFields">
       <doc xml:space="preserve"
            filename="annotation.h"
-           line="246">This is a struct for testing field documentation and annotations</doc>
-      <source-position filename="annotation.h" line="259"/>
+           line="252">This is a struct for testing field documentation and annotations</doc>
+      <source-position filename="annotation.h" line="273"/>
       <field name="field1" writable="1">
         <doc xml:space="preserve"
              filename="annotation.h"
-             line="248">Some documentation</doc>
+             line="254">Some documentation</doc>
         <type name="gint" c:type="int"/>
       </field>
       <field name="arr" writable="1">
         <doc xml:space="preserve"
              filename="annotation.h"
-             line="249">an array of length @len</doc>
+             line="255">an array of length @len</doc>
         <array length="2" zero-terminated="0" c:type="guchar*">
           <type name="guint8" c:type="guchar"/>
         </array>
@@ -160,13 +165,19 @@ and/or use gtk-doc annotations.  -->
       <field name="len" writable="1">
         <doc xml:space="preserve"
              filename="annotation.h"
-             line="250">the length of array</doc>
+             line="256">the length of array</doc>
         <type name="gulong" c:type="gulong"/>
       </field>
+      <field name="field4" version="1.4" writable="1">
+        <doc xml:space="preserve"
+             filename="annotation.h"
+             line="265">A new field, breaking ABI is fun!</doc>
+        <type name="guint" c:type="guint"/>
+      </field>
     </record>
     <callback name="AnnotationForeachFunc"
               c:type="RegressAnnotationForeachFunc">
-      <source-position filename="annotation.h" line="49"/>
+      <source-position filename="annotation.h" line="55"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
@@ -190,12 +201,12 @@ and/or use gtk-doc annotations.  -->
               c:type="RegressAnnotationListCallback">
       <doc xml:space="preserve"
            filename="annotation.h"
-           line="23">This is a callback taking a list.</doc>
-      <source-position filename="annotation.h" line="30"/>
+           line="29">This is a callback taking a list.</doc>
+      <source-position filename="annotation.h" line="36"/>
       <return-value transfer-ownership="container">
         <doc xml:space="preserve"
              filename="annotation.h"
-             line="28">list of strings</doc>
+             line="34">list of strings</doc>
         <type name="GLib.List" c:type="GList*">
           <type name="utf8"/>
         </type>
@@ -204,7 +215,7 @@ and/or use gtk-doc annotations.  -->
         <parameter name="in" transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.h"
-               line="25">list of strings</doc>
+               line="31">list of strings</doc>
           <type name="GLib.List" c:type="GList*">
             <type name="utf8"/>
           </type>
@@ -214,9 +225,9 @@ and/or use gtk-doc annotations.  -->
     <callback name="AnnotationNotifyFunc" c:type="RegressAnnotationNotifyFunc">
       <doc xml:space="preserve"
            filename="annotation.h"
-           line="32">This is a callback with a 'closure' argument that is not named
+           line="38">This is a callback with a 'closure' argument that is not named
 'user_data' and hence has to be annotated.</doc>
-      <source-position filename="annotation.h" line="39"/>
+      <source-position filename="annotation.h" line="45"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
@@ -228,7 +239,7 @@ and/or use gtk-doc annotations.  -->
                    closure="0">
           <doc xml:space="preserve"
                filename="annotation.h"
-               line="34">The user data</doc>
+               line="40">The user data</doc>
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
       </parameters>
@@ -243,11 +254,11 @@ and/or use gtk-doc annotations.  -->
       <attribute name="org.example.Test" value="cows"/>
       <doc xml:space="preserve"
            filename="annotation.h"
-           line="41">This is an object used to test annotations.</doc>
-      <source-position filename="annotation.h" line="61"/>
+           line="47">This is an object used to test annotations.</doc>
+      <source-position filename="annotation.h" line="67"/>
       <method name="allow_none"
               c:identifier="regress_annotation_object_allow_none">
-        <source-position filename="annotation.h" line="77"/>
+        <source-position filename="annotation.h" line="83"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -274,7 +285,7 @@ and/or use gtk-doc annotations.  -->
         <doc xml:space="preserve"
              filename="annotation.c"
              line="296">This is a test for out arguments; GObject defaults to transfer</doc>
-        <source-position filename="annotation.h" line="100"/>
+        <source-position filename="annotation.h" line="106"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -304,7 +315,7 @@ and/or use gtk-doc annotations.  -->
         <doc xml:space="preserve"
              filename="annotation.c"
              line="312">This is a test for out arguments, one transferred, other not</doc>
-        <source-position filename="annotation.h" line="104"/>
+        <source-position filename="annotation.h" line="110"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -343,7 +354,7 @@ and/or use gtk-doc annotations.  -->
         <doc xml:space="preserve"
              filename="annotation.c"
              line="422">Test taking a zero-terminated array</doc>
-        <source-position filename="annotation.h" line="128"/>
+        <source-position filename="annotation.h" line="134"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -369,7 +380,7 @@ and/or use gtk-doc annotations.  -->
         <doc xml:space="preserve"
              filename="annotation.c"
              line="436">Test taking an array with length parameter</doc>
-        <source-position filename="annotation.h" line="133"/>
+        <source-position filename="annotation.h" line="139"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -402,7 +413,7 @@ and/or use gtk-doc annotations.  -->
         <doc xml:space="preserve"
              filename="annotation.c"
              line="453">Test taking a zero-terminated array with length parameter</doc>
-        <source-position filename="annotation.h" line="138"/>
+        <source-position filename="annotation.h" line="144"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -435,7 +446,7 @@ are zero-terminated</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="396">Test returning a caller-owned object</doc>
-        <source-position filename="annotation.h" line="74"/>
+        <source-position filename="annotation.h" line="80"/>
         <return-value transfer-ownership="full">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -456,7 +467,7 @@ are zero-terminated</doc>
               deprecated="1"
               deprecated-version="0.12">
         <doc-deprecated xml:space="preserve">Use regress_annotation_object_create_object() instead.</doc-deprecated>
-        <source-position filename="annotation.h" line="174"/>
+        <source-position filename="annotation.h" line="180"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -475,7 +486,7 @@ are zero-terminated</doc>
       <method name="extra_annos"
               c:identifier="regress_annotation_object_extra_annos">
         <attribute name="org.foobar" value="testvalue"/>
-        <source-position filename="annotation.h" line="213"/>
+        <source-position filename="annotation.h" line="219"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -489,7 +500,7 @@ are zero-terminated</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="502">Test taking a call-scoped callback</doc>
-        <source-position filename="annotation.h" line="152"/>
+        <source-position filename="annotation.h" line="158"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -527,7 +538,7 @@ are zero-terminated</doc>
              filename="annotation.c"
              line="349">This is a test for returning a hash table mapping strings to
 objects.</doc>
-        <source-position filename="annotation.h" line="112"/>
+        <source-position filename="annotation.h" line="118"/>
         <return-value transfer-ownership="full">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -553,7 +564,7 @@ objects.</doc>
              line="378">This is a test for returning a list of objects.
 The list itself should be freed, but not the internal objects,
 intentionally similar example to gtk_container_get_children</doc>
-        <source-position filename="annotation.h" line="119"/>
+        <source-position filename="annotation.h" line="125"/>
         <return-value transfer-ownership="container">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -577,7 +588,7 @@ intentionally similar example to gtk_container_get_children</doc>
              filename="annotation.c"
              line="331">This is a test for returning a list of strings, where
 each string needs to be freed.</doc>
-        <source-position filename="annotation.h" line="109"/>
+        <source-position filename="annotation.h" line="115"/>
         <return-value transfer-ownership="full">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -597,7 +608,7 @@ each string needs to be freed.</doc>
       </method>
       <method name="hidden_self"
               c:identifier="regress_annotation_object_hidden_self">
-        <source-position filename="annotation.h" line="188"/>
+        <source-position filename="annotation.h" line="194"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -614,7 +625,7 @@ each string needs to be freed.</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="232">This is a test for in arguments</doc>
-        <source-position filename="annotation.h" line="96"/>
+        <source-position filename="annotation.h" line="102"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -640,7 +651,7 @@ each string needs to be freed.</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="248">This is a test for out arguments</doc>
-        <source-position filename="annotation.h" line="84"/>
+        <source-position filename="annotation.h" line="90"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -669,7 +680,7 @@ each string needs to be freed.</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="263">This is a second test for out arguments</doc>
-        <source-position filename="annotation.h" line="88"/>
+        <source-position filename="annotation.h" line="94"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -698,7 +709,7 @@ each string needs to be freed.</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="279">This is a 3th test for out arguments</doc>
-        <source-position filename="annotation.h" line="92"/>
+        <source-position filename="annotation.h" line="98"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -726,7 +737,7 @@ each string needs to be freed.</doc>
         </parameters>
       </method>
       <method name="method" c:identifier="regress_annotation_object_method">
-        <source-position filename="annotation.h" line="67"/>
+        <source-position filename="annotation.h" line="73"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -743,7 +754,7 @@ each string needs to be freed.</doc>
         </parameters>
       </method>
       <method name="notrans" c:identifier="regress_annotation_object_notrans">
-        <source-position filename="annotation.h" line="81"/>
+        <source-position filename="annotation.h" line="87"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -763,7 +774,7 @@ each string needs to be freed.</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="216">This is a test for out arguments</doc>
-        <source-position filename="annotation.h" line="70"/>
+        <source-position filename="annotation.h" line="76"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -793,7 +804,7 @@ each string needs to be freed.</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="470">Test taking a zero-terminated array with length parameter</doc>
-        <source-position filename="annotation.h" line="143"/>
+        <source-position filename="annotation.h" line="149"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -831,7 +842,7 @@ each string needs to be freed.</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="518">Test taking a guchar * with a length.</doc>
-        <source-position filename="annotation.h" line="158"/>
+        <source-position filename="annotation.h" line="164"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -863,7 +874,7 @@ each string needs to be freed.</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="534">Test taking a gchar * with a length.</doc>
-        <source-position filename="annotation.h" line="163"/>
+        <source-position filename="annotation.h" line="169"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -896,7 +907,7 @@ each string needs to be freed.</doc>
              filename="annotation.c"
              line="550">Test taking a gchar * with a length, overriding the array element
 type.</doc>
-        <source-position filename="annotation.h" line="168"/>
+        <source-position filename="annotation.h" line="174"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -928,7 +939,7 @@ type.</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="486">Test returning a string as an out parameter</doc>
-        <source-position filename="annotation.h" line="148"/>
+        <source-position filename="annotation.h" line="154"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve"
                filename="annotation.c"
@@ -955,7 +966,7 @@ type.</doc>
       </method>
       <method name="use_buffer"
               c:identifier="regress_annotation_object_use_buffer">
-        <source-position filename="annotation.h" line="123"/>
+        <source-position filename="annotation.h" line="129"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -979,7 +990,7 @@ type.</doc>
              filename="annotation.c"
              line="606">This is here just for the sake of being overriden by its
 regress_annotation_object_watch_full().</doc>
-        <source-position filename="annotation.h" line="177"/>
+        <source-position filename="annotation.h" line="183"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -1014,7 +1025,7 @@ regress_annotation_object_watch_full().</doc>
         <doc xml:space="preserve"
              filename="annotation.c"
              line="622">Test overriding via the "Rename To" annotation.</doc>
-        <source-position filename="annotation.h" line="182"/>
+        <source-position filename="annotation.h" line="188"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -1055,7 +1066,7 @@ regress_annotation_object_watch_full().</doc>
       </method>
       <method name="with_voidp"
               c:identifier="regress_annotation_object_with_voidp">
-        <source-position filename="annotation.h" line="115"/>
+        <source-position filename="annotation.h" line="121"/>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -1196,7 +1207,7 @@ it says it's pointer but it's actually a string.</doc>
     <record name="AnnotationObjectClass"
             c:type="RegressAnnotationObjectClass"
             glib:is-gtype-struct-for="AnnotationObject">
-      <source-position filename="annotation.h" line="61"/>
+      <source-position filename="annotation.h" line="67"/>
       <field name="parent_class">
         <type name="GObject.ObjectClass" c:type="GObjectClass"/>
       </field>
@@ -1204,8 +1215,8 @@ it says it's pointer but it's actually a string.</doc>
     <record name="AnnotationStruct" c:type="RegressAnnotationStruct">
       <doc xml:space="preserve"
            filename="annotation.h"
-           line="236">This is a test of an array of object in an field of a struct.</doc>
-      <source-position filename="annotation.h" line="244"/>
+           line="242">This is a test of an array of object in an field of a struct.</doc>
+      <source-position filename="annotation.h" line="250"/>
       <field name="objects" writable="1">
         <array zero-terminated="0" fixed-size="10">
           <type name="AnnotationObject" c:type="RegressAnnotationObject*"/>
@@ -5648,7 +5659,7 @@ the introspection client langage.</doc>
     </function>
     <function name="annotation_attribute_func"
               c:identifier="regress_annotation_attribute_func">
-      <source-position filename="annotation.h" line="229"/>
+      <source-position filename="annotation.h" line="235"/>
       <return-value transfer-ownership="none">
         <attribute name="some.other.annotation" value="value2"/>
         <attribute name="yet.another.annotation" value="another_value"/>
@@ -5680,7 +5691,7 @@ the introspection client langage.</doc>
            filename="annotation.c"
            line="719">Test messing up the heuristic of closure/destroy-notification
 detection, and fixing it via annotations.</doc>
-      <source-position filename="annotation.h" line="217"/>
+      <source-position filename="annotation.h" line="223"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
@@ -5712,7 +5723,7 @@ detection, and fixing it via annotations.</doc>
     </function>
     <function name="annotation_get_source_file"
               c:identifier="regress_annotation_get_source_file">
-      <source-position filename="annotation.h" line="222"/>
+      <source-position filename="annotation.h" line="228"/>
       <return-value transfer-ownership="full">
         <doc xml:space="preserve"
              filename="annotation.c"
@@ -5721,7 +5732,7 @@ detection, and fixing it via annotations.</doc>
       </return-value>
     </function>
     <function name="annotation_init" c:identifier="regress_annotation_init">
-      <source-position filename="annotation.h" line="192"/>
+      <source-position filename="annotation.h" line="198"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
@@ -5750,7 +5761,7 @@ detection, and fixing it via annotations.</doc>
     </function>
     <function name="annotation_invalid_regress_annotation"
               c:identifier="regress_annotation_invalid_regress_annotation">
-      <source-position filename="annotation.h" line="234"/>
+      <source-position filename="annotation.h" line="240"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
@@ -5765,7 +5776,7 @@ detection, and fixing it via annotations.</doc>
     </function>
     <function name="annotation_ptr_array"
               c:identifier="regress_annotation_ptr_array">
-      <source-position filename="annotation.h" line="263"/>
+      <source-position filename="annotation.h" line="276"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
@@ -5782,7 +5793,7 @@ detection, and fixing it via annotations.</doc>
     </function>
     <function name="annotation_return_array"
               c:identifier="regress_annotation_return_array">
-      <source-position filename="annotation.h" line="196"/>
+      <source-position filename="annotation.h" line="202"/>
       <return-value transfer-ownership="full">
         <doc xml:space="preserve"
              filename="annotation.c"
@@ -5805,7 +5816,7 @@ detection, and fixing it via annotations.</doc>
     </function>
     <function name="annotation_return_filename"
               c:identifier="regress_annotation_return_filename">
-      <source-position filename="annotation.h" line="275"/>
+      <source-position filename="annotation.h" line="288"/>
       <return-value transfer-ownership="full">
         <doc xml:space="preserve"
              filename="annotation.c"
@@ -5815,7 +5826,7 @@ detection, and fixing it via annotations.</doc>
     </function>
     <function name="annotation_set_source_file"
               c:identifier="regress_annotation_set_source_file">
-      <source-position filename="annotation.h" line="225"/>
+      <source-position filename="annotation.h" line="231"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
@@ -5833,14 +5844,14 @@ detection, and fixing it via annotations.</doc>
       <doc xml:space="preserve"
            filename="annotation.c"
            line="805">Explicitly test having a space after the ** here.</doc>
-      <source-position filename="annotation.h" line="271"/>
+      <source-position filename="annotation.h" line="284"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
     </function>
     <function name="annotation_string_array_length"
               c:identifier="regress_annotation_string_array_length">
-      <source-position filename="annotation.h" line="209"/>
+      <source-position filename="annotation.h" line="215"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
@@ -5857,7 +5868,7 @@ detection, and fixing it via annotations.</doc>
     </function>
     <function name="annotation_string_zero_terminated"
               c:identifier="regress_annotation_string_zero_terminated">
-      <source-position filename="annotation.h" line="202"/>
+      <source-position filename="annotation.h" line="208"/>
       <return-value transfer-ownership="full">
         <doc xml:space="preserve"
              filename="annotation.c"
@@ -5869,7 +5880,7 @@ detection, and fixing it via annotations.</doc>
     </function>
     <function name="annotation_string_zero_terminated_out"
               c:identifier="regress_annotation_string_zero_terminated_out">
-      <source-position filename="annotation.h" line="205"/>
+      <source-position filename="annotation.h" line="211"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
@@ -5889,7 +5900,7 @@ detection, and fixing it via annotations.</doc>
       <doc xml:space="preserve"
            filename="annotation.c"
            line="791">See https://bugzilla.gnome.org/show_bug.cgi?id=630862</doc>
-      <source-position filename="annotation.h" line="267"/>
+      <source-position filename="annotation.h" line="280"/>
       <return-value transfer-ownership="none">
         <doc xml:space="preserve"
              filename="annotation.c"
@@ -5899,7 +5910,7 @@ detection, and fixing it via annotations.</doc>
     </function>
     <function name="annotation_transfer_floating"
               c:identifier="regress_annotation_transfer_floating">
-      <source-position filename="annotation.h" line="279"/>
+      <source-position filename="annotation.h" line="292"/>
       <return-value transfer-ownership="none">
         <doc xml:space="preserve"
              filename="annotation.c"
@@ -5918,7 +5929,7 @@ detection, and fixing it via annotations.</doc>
     <function name="annotation_versioned"
               c:identifier="regress_annotation_versioned"
               version="0.6">
-      <source-position filename="annotation.h" line="199"/>
+      <source-position filename="annotation.h" line="205"/>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
diff --git a/tests/scanner/annotation.h b/tests/scanner/annotation.h
index 92c0b6bd..5c23d77c 100644
--- a/tests/scanner/annotation.h
+++ b/tests/scanner/annotation.h
@@ -8,7 +8,13 @@
 typedef enum /*< flags,prefix=ANN >*/
 {
   ANN_FLAG_FOO = 1,
-  ANN_FLAG_BAR = 2
+  ANN_FLAG_BAR = 2,
+  /**
+   * ANN_FLAG_FOOBAR:
+   *
+   * Since: 1.4
+   */
+  ANN_FLAG_FOOBAR = 3,
 } RegressAnnotationBitfield;
 
 /**
@@ -256,9 +262,16 @@ struct RegressAnnotationFields
   int field1;
   guchar *arr;
   gulong len;
+  /**
+   * RegressAnnotationFields.field4:
+   *
+   * A new field, breaking ABI is fun!
+   *
+   * Since: 1.4
+   */
+  guint field4;
 };
 
-
 _GI_TEST_EXTERN
 void    regress_annotation_ptr_array (GPtrArray *array);
 
-- 
cgit v1.2.1