Merge pull request #113 from gtk-rs/create-pull-request/patch

Update GIR files (2022-05-01)

GLib-2.0.gir

@@ -7701,8 +7701,14 @@ as appropriate for a given platform. IEEE floats and doubles are supported
     bytes, and return units in bits. For example, &#x2018;Mb&#x2019; rather than &#x2018;MB&#x2019;.</doc>
       </member>
       <member name="only_value" value="8" c:identifier="G_FORMAT_SIZE_ONLY_VALUE">
+        <doc xml:space="preserve">return only value, without unit; this should
+    not be used together with @G_FORMAT_SIZE_LONG_FORMAT
+    nor @G_FORMAT_SIZE_ONLY_UNIT. Since: 2.74</doc>
       </member>
       <member name="only_unit" value="16" c:identifier="G_FORMAT_SIZE_ONLY_UNIT">
+        <doc xml:space="preserve">return only unit, without value; this should
+    not be used together with @G_FORMAT_SIZE_LONG_FORMAT
+    nor @G_FORMAT_SIZE_ONLY_VALUE. Since: 2.74</doc>
       </member>
     </bitfield>
     <callback name="FreeFunc" c:type="GFreeFunc">
@@ -9977,15 +9983,15 @@ situation.</doc>
             <doc xml:space="preserve">bytes to convert</doc>
             <type name="utf8" c:type="gchar**"/>
           </parameter>
-          <parameter name="inbytes_left" transfer-ownership="none">
+          <parameter name="inbytes_left" direction="inout" caller-allocates="0" transfer-ownership="full">
             <doc xml:space="preserve">inout parameter, bytes remaining to convert in @inbuf</doc>
             <type name="gsize" c:type="gsize*"/>
           </parameter>
           <parameter name="outbuf" transfer-ownership="none">
             <doc xml:space="preserve">converted output bytes</doc>
             <type name="utf8" c:type="gchar**"/>
           </parameter>
-          <parameter name="outbytes_left" transfer-ownership="none">
+          <parameter name="outbytes_left" direction="inout" caller-allocates="0" transfer-ownership="full">
             <doc xml:space="preserve">inout parameter, bytes available to fill in @outbuf</doc>
             <type name="gsize" c:type="gsize*"/>
           </parameter>
@@ -27578,9 +27584,15 @@ when you are done with it.</doc>
 in seconds.
 
 This is equivalent to calling g_time_zone_new() with a string in the form
-`[+|-]hh[:mm[:ss]]`.</doc>
+`[+|-]hh[:mm[:ss]]`.
+
+It is possible for this function to fail if @seconds is too big (greater than
+24 hours), in which case this function will return the UTC timezone for
+backwards compatibility. To detect failures like this, use
+g_time_zone_new_identifier() directly.</doc>
         <return-value transfer-ownership="full">
-          <doc xml:space="preserve">a timezone at the given offset from UTC</doc>
+          <doc xml:space="preserve">a timezone at the given offset from UTC, or UTC on
+  failure</doc>
           <type name="TimeZone" c:type="GTimeZone*"/>
         </return-value>
         <parameters>
@@ -43631,15 +43643,15 @@ situation.</doc>
           <doc xml:space="preserve">bytes to convert</doc>
           <type name="utf8" c:type="gchar**"/>
         </parameter>
-        <parameter name="inbytes_left" transfer-ownership="none">
+        <parameter name="inbytes_left" direction="inout" caller-allocates="0" transfer-ownership="full">
           <doc xml:space="preserve">inout parameter, bytes remaining to convert in @inbuf</doc>
           <type name="gsize" c:type="gsize*"/>
         </parameter>
         <parameter name="outbuf" transfer-ownership="none">
           <doc xml:space="preserve">converted output bytes</doc>
           <type name="utf8" c:type="gchar**"/>
         </parameter>
-        <parameter name="outbytes_left" transfer-ownership="none">
+        <parameter name="outbytes_left" direction="inout" caller-allocates="0" transfer-ownership="full">
           <doc xml:space="preserve">inout parameter, bytes available to fill in @outbuf</doc>
           <type name="gsize" c:type="gsize*"/>
         </parameter>
@@ -56538,7 +56550,7 @@ of characters instead of a given number of bytes. The @src string
 must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
 text before trying to use UTF-8 utility functions with it.)
 
-Note you must ensure @dest is at least 4 * @n to fit the
+Note you must ensure @dest is at least 4 * @n + 1 to fit the
 largest possible UTF-8 characters</doc>
       <return-value transfer-ownership="none">
         <doc xml:space="preserve">@dest</doc>

GObject-2.0.gir

@@ -3708,14 +3708,49 @@ types, over calling g_boxed_type_register_static() directly. It defines
 a `type_name_get_type()` function which will return the newly defined
 #GType, enabling lazy instantiation.
 
+You might start by putting declarations in a header as follows:
+
+|[<!-- language="C" -->
+#define MY_TYPE_STRUCT my_struct_get_type ()
+GType my_struct_get_type (void) G_GNUC_CONST;
+
+MyStruct *    my_struct_new (void);
+void          my_struct_free (MyStruct *self);
+MyStruct *    my_struct_copy (MyStruct *self);
+]|
+
+And then use this macro and define your implementation in the source file as
+follows:
+
 |[<!-- language="C" -->
+MyStruct *
+my_struct_new (void)
+{
+  // ... your code to allocate a new MyStruct ...
+}
+
+void
+my_struct_free (MyStruct *self)
+{
+  // ... your code to free a MyStruct ...
+}
+
+MyStruct *
+my_struct_copy (MyStruct *self)
+{
+  // ... your code return a newly allocated copy of a MyStruct ...
+}
+
 G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free)
 
 void
 foo ()
 {
-  GType type = my_struct_get_type ();
+  MyStruct *ms;
+
+  ms = my_struct_new ();
   // ... your code ...
+  my_struct_free (ms);
 }
 ]|</doc>
       <parameters>
@@ -8894,21 +8929,29 @@ You cannot connect a signal handler after #GSignalGroup:target has been set.</do
           </parameter>
         </parameters>
       </method>
-      <method name="connect_closure" c:identifier="g_signal_group_connect_closure">
+      <method name="connect_closure" c:identifier="g_signal_group_connect_closure" version="2.74">
+        <doc xml:space="preserve">Connects @closure to the signal @detailed_signal on #GSignalGroup:target.
+
+You cannot connect a signal handler after #GSignalGroup:target has been set.</doc>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
         <parameters>
           <instance-parameter name="self" transfer-ownership="none">
+            <doc xml:space="preserve">a #GSignalGroup</doc>
             <type name="SignalGroup" c:type="GSignalGroup*"/>
           </instance-parameter>
           <parameter name="detailed_signal" transfer-ownership="none">
+            <doc xml:space="preserve">a string of the form `signal-name` with optional `::signal-detail`</doc>
             <type name="utf8" c:type="const gchar*"/>
           </parameter>
           <parameter name="closure" transfer-ownership="none">
+            <doc xml:space="preserve">the closure to connect.</doc>
             <type name="Closure" c:type="GClosure*"/>
           </parameter>
           <parameter name="after" transfer-ownership="none">
+            <doc xml:space="preserve">whether the handler should be called before or after the
+ default handler of the signal.</doc>
             <type name="gboolean" c:type="gboolean"/>
           </parameter>
         </parameters>

Gio-2.0.gir

@@ -46656,7 +46656,7 @@ set to the position where @item occurred for the first time.</doc>
       </method>
       <method name="find_with_equal_func" c:identifier="g_list_store_find_with_equal_func" version="2.64">
         <doc xml:space="preserve">Looks up the given @item in the list store by looping over the items and
-comparing them with @compare_func until the first occurrence of @item which
+comparing them with @equal_func until the first occurrence of @item which
 matches. If @item was not found, then @position will not be set, and this
 method will return %FALSE.</doc>
         <return-value transfer-ownership="none">
@@ -46683,24 +46683,33 @@ set to the position where @item occurred for the first time.</doc>
           </parameter>
         </parameters>
       </method>
-      <method name="find_with_equal_func_full" c:identifier="g_list_store_find_with_equal_func_full" introspectable="0">
+      <method name="find_with_equal_func_full" c:identifier="g_list_store_find_with_equal_func_full" version="2.74">
+        <doc xml:space="preserve">Like g_list_store_find_with_equal_func() but with an additional @user_data
+that is passed to @equal_func.</doc>
         <return-value transfer-ownership="none">
+          <doc xml:space="preserve">Whether @store contains @item. If it was found, @position will be
+set to the position where @item occurred for the first time.</doc>
           <type name="gboolean" c:type="gboolean"/>
         </return-value>
         <parameters>
           <instance-parameter name="store" transfer-ownership="none">
+            <doc xml:space="preserve">a #GListStore</doc>
             <type name="ListStore" c:type="GListStore*"/>
           </instance-parameter>
-          <parameter name="item" transfer-ownership="none" nullable="1" allow-none="1">
-            <type name="gpointer" c:type="gpointer"/>
+          <parameter name="item" transfer-ownership="none">
+            <doc xml:space="preserve">an item</doc>
+            <type name="GObject.Object" c:type="gpointer"/>
           </parameter>
-          <parameter name="equal_func" transfer-ownership="none" closure="2">
+          <parameter name="equal_func" transfer-ownership="none" scope="call" closure="2">
+            <doc xml:space="preserve">A custom equality check function</doc>
             <type name="GLib.EqualFuncFull" c:type="GEqualFuncFull"/>
           </parameter>
           <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
+            <doc xml:space="preserve">user data for @equal_func</doc>
             <type name="gpointer" c:type="gpointer"/>
           </parameter>
-          <parameter name="position" transfer-ownership="none">
+          <parameter name="position" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
+            <doc xml:space="preserve">the first position of @item, if it was found.</doc>
             <type name="guint" c:type="guint*"/>
           </parameter>
         </parameters>
@@ -57269,10 +57278,10 @@ whether the system is in &#x201C;Power Saver&#x201D; mode (known as &#x201C;Low
 some systems).
 
 When in &#x201C;Low Power&#x201D; mode, it is recommended that applications:
-- disabling automatic downloads
+- disable automatic downloads;
 - reduce the rate of refresh from online sources such as calendar or
-  email synchronisation
-- if the application has expensive visual effects, reduce them
+  email synchronisation;
+- reduce the use of expensive visual effects.
 
 It is also likely that OS components providing services to applications will
 lower their own background activity, for the sake of the system.
@@ -76358,7 +76367,7 @@ client-side connections, unless that bit is not set in
 #GTlsClientConnection:validation-flags).
 
 There are nonintuitive security implications when using a non-default
-database. See #GDtlsConnection:database for details.</doc>
+database. See #GTlsConnection:database for details.</doc>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>

Gtk-4.0.gir

@@ -61090,7 +61090,7 @@ on the parent widget or on any of its parent widgets.
 The only flag that is supported currently is
 %GTK_POPOVER_MENU_NESTED, which makes GTK create traditional,
 nested submenus instead of the default sliding submenus.</doc>
-        <return-value transfer-ownership="full">
+        <return-value transfer-ownership="none">
           <doc xml:space="preserve">the new `GtkPopoverMenu`</doc>
           <type name="Widget" c:type="GtkWidget*"/>
         </return-value>