Add support for element-type to GListModel

GListModel is an interface for creating typed, list-like containers. The
data stored is GObject instances, but it's useful to be able to annotate
the actual type, for both documentation and code generation purposes.

The annotation should be optional, to maintain backward compatibility.

10 files changed, 259 insertions, 0 deletions

diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.test_list_model_none.page b/tests/scanner/Regress-1.0-C-expected/Regress.test_list_model_none.page
new file mode 100644
index 00000000..b1458649
--- /dev/null
+++ b/tests/scanner/Regress-1.0-C-expected/Regress.test_list_model_none.page
@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<page id="Regress.test_list_model_none"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="index" group="function" type="guide"/>
+    <api:function>
+      <api:returns>
+        <api:type>GListModel*</api:type>
+      </api:returns>
+      <api:name>regress_test_list_model_none</api:name>
+    </api:function>
+  </info>
+  <title>regress_test_list_model_none</title>
+  <synopsis><code mime="text/x-csrc">
+GListModel* regress_test_list_model_none (void);
+  </code></synopsis>
+  <p>Test GListModel with no annotation.</p>
+
+<terms>
+<item>
+<title><code>Returns</code></title>
+  <p>a GListModel</p>
+</item>
+</terms>
+
+</page>
diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.test_list_model_object.page b/tests/scanner/Regress-1.0-C-expected/Regress.test_list_model_object.page
new file mode 100644
index 00000000..620789cd
--- /dev/null
+++ b/tests/scanner/Regress-1.0-C-expected/Regress.test_list_model_object.page
@@ -0,0 +1,31 @@
+<?xml version="1.0"?>
+<page id="Regress.test_list_model_object"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="index" group="function" type="guide"/>
+    <api:function>
+      <api:returns>
+        <api:type>GListModel*</api:type>
+      </api:returns>
+      <api:name>regress_test_list_model_object</api:name>
+    </api:function>
+  </info>
+  <title>regress_test_list_model_object</title>
+  <synopsis><code mime="text/x-csrc">
+GListModel* regress_test_list_model_object (void);
+  </code></synopsis>
+  <p>Test GListModel return value with an element type annotation.</p>
+
+<terms>
+<item>
+<title><code>Returns</code></title>
+  <p>a GListModel
+  containing RegressTestObj values</p>
+</item>
+</terms>
+
+</page>
diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_list_model_none.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_list_model_none.page
new file mode 100644
index 00000000..099232e0
--- /dev/null
+++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_list_model_none.page
@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<page id="Regress.test_list_model_none"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="index" group="function" type="guide"/>
+    <api:function>
+      <api:returns>
+        <api:type>Gio.ListModel({item_type: void})</api:type>
+      </api:returns>
+      <api:name>regress_test_list_model_none</api:name>
+    </api:function>
+  </info>
+  <title>Regress.test_list_model_none</title>
+  <synopsis><code mime="text/x-gjs">
+function test_list_model_none(): Gio.ListModel({item_type: void}) {
+    // Gjs wrapper for regress_test_list_model_none()
+}
+  </code></synopsis>
+  <p>Test GListModel with no annotation.</p>
+
+<terms>
+<item>
+<title><code>Returns</code></title>
+  <p>a GListModel</p>
+</item>
+</terms>
+
+</page>
diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_list_model_object.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_list_model_object.page
new file mode 100644
index 00000000..618ca7e3
--- /dev/null
+++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_list_model_object.page
@@ -0,0 +1,33 @@
+<?xml version="1.0"?>
+<page id="Regress.test_list_model_object"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="index" group="function" type="guide"/>
+    <api:function>
+      <api:returns>
+        <api:type>Gio.ListModel({item_type: Regress.TestObj})</api:type>
+      </api:returns>
+      <api:name>regress_test_list_model_object</api:name>
+    </api:function>
+  </info>
+  <title>Regress.test_list_model_object</title>
+  <synopsis><code mime="text/x-gjs">
+function test_list_model_object(): Gio.ListModel({item_type: Regress.TestObj}) {
+    // Gjs wrapper for regress_test_list_model_object()
+}
+  </code></synopsis>
+  <p>Test GListModel return value with an element type annotation.</p>
+
+<terms>
+<item>
+<title><code>Returns</code></title>
+  <p>a GListModel
+  containing RegressTestObj values</p>
+</item>
+</terms>
+
+</page>
diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.test_list_model_none.page b/tests/scanner/Regress-1.0-Python-expected/Regress.test_list_model_none.page
new file mode 100644
index 00000000..61cb3de1
--- /dev/null
+++ b/tests/scanner/Regress-1.0-Python-expected/Regress.test_list_model_none.page
@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<page id="Regress.test_list_model_none"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="index" group="function" type="guide"/>
+    <api:function>
+      <api:returns>
+        <api:type>Gio.ListModel(item_type=gpointer)</api:type>
+      </api:returns>
+      <api:name>regress_test_list_model_none</api:name>
+    </api:function>
+  </info>
+  <title>Regress.test_list_model_none</title>
+  <synopsis><code mime="text/x-python">
+@returns(Gio.ListModel(item_type=gpointer))
+def test_list_model_none():
+    # Python wrapper for regress_test_list_model_none()
+  </code></synopsis>
+  <p>Test GListModel with no annotation.</p>
+
+<terms>
+<item>
+<title><code>Returns</code></title>
+{formatter.format(node, node.retval.doc)}
+</item>
+</terms>
+
+</page>
diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.test_list_model_object.page b/tests/scanner/Regress-1.0-Python-expected/Regress.test_list_model_object.page
new file mode 100644
index 00000000..d9dca201
--- /dev/null
+++ b/tests/scanner/Regress-1.0-Python-expected/Regress.test_list_model_object.page
@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<page id="Regress.test_list_model_object"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/1.0/ui/">
+  <info>
+    <link xref="index" group="function" type="guide"/>
+    <api:function>
+      <api:returns>
+        <api:type>Gio.ListModel(item_type=Regress.TestObj)</api:type>
+      </api:returns>
+      <api:name>regress_test_list_model_object</api:name>
+    </api:function>
+  </info>
+  <title>Regress.test_list_model_object</title>
+  <synopsis><code mime="text/x-python">
+@returns(Gio.ListModel(item_type=Regress.TestObj))
+def test_list_model_object():
+    # Python wrapper for regress_test_list_model_object()
+  </code></synopsis>
+  <p>Test GListModel return value with an element type annotation.</p>
+
+<terms>
+<item>
+<title><code>Returns</code></title>
+{formatter.format(node, node.retval.doc)}
+</item>
+</terms>
+
+</page>
diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir
index cef3b124..bcba3fbe 100644
--- a/tests/scanner/Regress-1.0-expected.gir
+++ b/tests/scanner/Regress-1.0-expected.gir
@@ -8041,6 +8041,37 @@ element-type annotation.</doc>
         </parameter>
       </parameters>
     </function>
+    <function name="test_list_model_none"
+              c:identifier="regress_test_list_model_none">
+      <doc xml:space="preserve"
+           filename="regress.c"
+           line="4689">Test GListModel with no annotation.</doc>
+      <source-position filename="regress.h" line="1538"/>
+      <return-value transfer-ownership="full">
+        <doc xml:space="preserve"
+             filename="regress.c"
+             line="4694">a GListModel</doc>
+        <type name="Gio.ListModel" c:type="GListModel*">
+          <type name="gpointer" c:type="gpointer"/>
+        </type>
+      </return-value>
+    </function>
+    <function name="test_list_model_object"
+              c:identifier="regress_test_list_model_object">
+      <doc xml:space="preserve"
+           filename="regress.c"
+           line="4704">Test GListModel return value with an element type annotation.</doc>
+      <source-position filename="regress.h" line="1541"/>
+      <return-value transfer-ownership="full">
+        <doc xml:space="preserve"
+             filename="regress.c"
+             line="4709">a GListModel
+  containing RegressTestObj values</doc>
+        <type name="Gio.ListModel" c:type="GListModel*">
+          <type name="TestObj"/>
+        </type>
+      </return-value>
+    </function>
     <function name="test_long" c:identifier="regress_test_long">
       <source-position filename="regress.h" line="73"/>
       <return-value transfer-ownership="none">
diff --git a/tests/scanner/Regress-1.0-sections-expected.txt b/tests/scanner/Regress-1.0-sections-expected.txt
index b35b3a9a..84f7ec67 100644
--- a/tests/scanner/Regress-1.0-sections-expected.txt
+++ b/tests/scanner/Regress-1.0-sections-expected.txt
@@ -159,6 +159,8 @@ regress_test_int64
 regress_test_int8
 regress_test_int_out_utf8
 regress_test_int_value_arg
+regress_test_list_model_none
+regress_test_list_model_object
 regress_test_long
 regress_test_multi_callback
 regress_test_multi_double_args
diff --git a/tests/scanner/regress.c b/tests/scanner/regress.c
index 3a63436b..e81d1989 100644
--- a/tests/scanner/regress.c
+++ b/tests/scanner/regress.c
@@ -4686,3 +4686,33 @@ regress_test_array_struct_in_none (RegressTestStructA *arr, gsize len)
   g_assert_cmpint (arr[2].some_int, ==, 303);
 }
 
+/**
+ * regress_test_list_model_none:
+ *
+ * Test GListModel with no annotation.
+ *
+ * Returns: (transfer full): a GListModel
+ */
+GListModel *
+regress_test_list_model_none (void)
+{
+  GListStore *res = g_list_store_new (regress_test_obj_get_type ());
+
+  return G_LIST_MODEL (res);
+}
+
+/**
+ * regress_test_list_model_object:
+ *
+ * Test GListModel return value with an element type annotation.
+ *
+ * Returns: (transfer full) (element-type RegressTestObj): a GListModel
+ *   containing RegressTestObj values
+ */
+GListModel *
+regress_test_list_model_object (void)
+{
+  GListStore *res = g_list_store_new (regress_test_obj_get_type ());
+
+  return G_LIST_MODEL (res);
+}
diff --git a/tests/scanner/regress.h b/tests/scanner/regress.h
index 0b239f14..9ff699fb 100644
--- a/tests/scanner/regress.h
+++ b/tests/scanner/regress.h
@@ -1534,4 +1534,10 @@ void regress_test_array_struct_in_full (RegressTestStructA *arr, gsize len);
 _GI_TEST_EXTERN
 void regress_test_array_struct_in_none (RegressTestStructA *arr, gsize len);
 
+_GI_TEST_EXTERN
+GListModel *regress_test_list_model_none (void);
+
+_GI_TEST_EXTERN
+GListModel *regress_test_list_model_object (void);
+
 #endif /* __GITESTTYPES_H__ */