Glib, Gio: Regenerate docs.xml and .defs files

1 files changed, 267 insertions, 54 deletions

diff --git a/gio/src/gio_docs.xml b/gio/src/gio_docs.xml
index 38ba91c7..b55b91b8 100644
--- a/gio/src/gio_docs.xml
+++ b/gio/src/gio_docs.xml
@@ -4101,11 +4101,7 @@ appears to be able to reach the full Internet.
 
 <signal name="GNetworkMonitor::network-changed">
 <description>
-Emitted when the network configuration changes. If @available is
-%TRUE, then some hosts may be reachable that were not reachable
-before, while others that were reachable before may no longer be
-reachable. If @available is %FALSE, then no remote hosts are
-reachable.
+Emitted when the network configuration changes.
 
 Since: 2.32
 
@@ -4115,7 +4111,7 @@ Since: 2.32
 <parameter_description> a #GNetworkMonitor
 </parameter_description>
 </parameter>
-<parameter name="available">
+<parameter name="network_available">
 <parameter_description> the current value of #GNetworkMonitor:network-available
 </parameter_description>
 </parameter>
@@ -5423,7 +5419,7 @@ of fixed maximum length (e.g. SCTP).
 <description>
 Flags to define the behaviour of a #GSubprocess.
 
-Note that the default for stdin is to redirect from /dev/null.  For
+Note that the default for stdin is to redirect from `/dev/null`.  For
 stdout and stderr the default are for them to inherit the
 corresponding descriptor from the calling process.
 
@@ -5458,7 +5454,7 @@ g_subprocess_get_stdout_pipe().
 </parameter>
 <parameter name="G_SUBPROCESS_FLAGS_STDOUT_SILENCE">
 <parameter_description> silence the stdout of the spawned
-process (ie: redirect to /dev/null).
+process (ie: redirect to `/dev/null`).
 </parameter_description>
 </parameter>
 <parameter name="G_SUBPROCESS_FLAGS_STDERR_PIPE">
@@ -5469,7 +5465,7 @@ g_subprocess_get_stderr_pipe().
 </parameter>
 <parameter name="G_SUBPROCESS_FLAGS_STDERR_SILENCE">
 <parameter_description> silence the stderr of the spawned
-process (ie: redirect to /dev/null).
+process (ie: redirect to `/dev/null`).
 </parameter_description>
 </parameter>
 <parameter name="G_SUBPROCESS_FLAGS_STDERR_MERGE">
@@ -5793,19 +5789,22 @@ Since: 2.28
 
 <property name="GTlsClientConnection:use-ssl3">
 <description>
-If %TRUE, tells the connection to use a fallback version of TLS
+If %TRUE, forces the connection to use a fallback version of TLS
 or SSL, rather than trying to negotiate the best version of TLS
 to use. This can be used when talking to servers that don't
 implement version negotiation correctly and therefore refuse to
-handshake at all with a &quot;modern&quot; TLS handshake.
+handshake at all with a modern TLS handshake.
 
-Despite the property name, the fallback version is not
-necessarily SSL 3.0; if SSL 3.0 has been disabled, the
-#GTlsClientConnection will use the next highest available version
-(normally TLS 1.0) as the fallback version.
+Despite the property name, the fallback version is usually not
+SSL 3.0, because SSL 3.0 is generally disabled by the #GTlsBackend.
+#GTlsClientConnection will use the next-highest available version
+as the fallback version.
 
 Since: 2.28
 
+Deprecated: 2.56: SSL 3.0 is insecure, and this property does not
+generally enable or disable it, despite its name.
+
 </description>
 </property>
 
@@ -9872,23 +9871,47 @@ Checks if @application_id is a valid application identifier.
 A valid ID is required for calls to g_application_new() and
 g_application_set_application_id().
 
+Application identifiers follow the same format as
+[D-Bus well-known bus names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
 For convenience, the restrictions on application identifiers are
 reproduced here:
 
-- Application identifiers must contain only the ASCII characters
-&quot;[A-Z][a-z][0-9]_-.&quot; and must not begin with a digit.
+- Application identifiers are composed of 1 or more elements separated by a
+period (`.`) character. All elements must contain at least one character.
 
-- Application identifiers must contain at least one '.' (period)
-character (and thus at least two elements).
+- Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`,
+with `-` discouraged in new application identifiers. Each element must not
+begin with a digit.
 
-- Application identifiers must not begin or end with a '.' (period)
-character.
+- Application identifiers must contain at least one `.` (period) character
+(and thus at least two elements).
 
-- Application identifiers must not contain consecutive '.' (period)
-characters.
+- Application identifiers must not begin with a `.` (period) character.
 
 - Application identifiers must not exceed 255 characters.
 
+Note that the hyphen (`-`) character is allowed in application identifiers,
+but is problematic or not allowed in various specifications and APIs that
+refer to D-Bus, such as
+[Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers),
+the
+[`DBusActivatable` interface in the Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus),
+and the convention that an application's &quot;main&quot; interface and object path
+resemble its application identifier and bus name. To avoid situations that
+require special-case handling, it is recommended that new application
+identifiers consistently replace hyphens with underscores.
+
+Like D-Bus interface names, application identifiers should start with the
+reversed DNS domain name of the author of the interface (in lower-case), and
+it is conventional for the rest of the application identifier to consist of
+words run together, with initial capital letters.
+
+As with D-Bus interface names, if the author's DNS domain name contains
+hyphen/minus characters they should be replaced by underscores, and if it
+contains leading digits they should be escaped by prepending an underscore.
+For example, if the owner of 7-zip.org used an application identifier for an
+archiving application, it might be named `org._7_zip.Archiver`.
+
 
 </description>
 <parameters>
@@ -10371,6 +10394,78 @@ Since: 2.28
 <return></return>
 </function>
 
+<function name="g_application_set_option_context_description">
+<description>
+Adds a description to the @application option context.
+
+See g_option_context_set_description() for more information.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="application">
+<parameter_description> the #GApplication
+</parameter_description>
+</parameter>
+<parameter name="description">
+<parameter_description> a string to be shown in `--help` output
+after the list of options, or %NULL
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="g_application_set_option_context_parameter_string">
+<description>
+Sets the parameter string to be used by the commandline handling of @application.
+
+This function registers the argument to be passed to g_option_context_new()
+when the internal #GOptionContext of @application is created.
+
+See g_option_context_new() for more information about @parameter_string.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="application">
+<parameter_description> the #GApplication
+</parameter_description>
+</parameter>
+<parameter name="parameter_string">
+<parameter_description> a string which is displayed
+in the first line of `--help` output, after the usage summary `programname [OPTION...]`.
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="g_application_set_option_context_summary">
+<description>
+Adds a summary to the @application option context.
+
+See g_option_context_set_summary() for more information.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="application">
+<parameter_description> the #GApplication
+</parameter_description>
+</parameter>
+<parameter name="summary">
+<parameter_description> a string to be shown in `--help` output
+before the list of options, or %NULL
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
 <function name="g_application_set_resource_base_path">
 <description>
 Sets (or unsets) the base resource path of @application.
@@ -13483,6 +13578,8 @@ functions will be marked as deprecated in a future release.  Use
 g_data_input_stream_read_upto() instead, but note that that function
 does not consume the stop character.
 
+Deprecated: 2.56: Use g_data_input_stream_read_upto() instead, which has more
+consistent behaviour regarding the stop character.
 
 </description>
 <parameters>
@@ -13533,6 +13630,8 @@ will be marked as deprecated in a future release.  Use
 g_data_input_stream_read_upto_async() instead.
 
 Since: 2.20
+Deprecated: 2.56: Use g_data_input_stream_read_upto_async() instead, which
+has more consistent behaviour regarding the stop character.
 
 </description>
 <parameters>
@@ -13571,6 +13670,8 @@ g_data_input_stream_read_until_async().
 
 Since: 2.20
 
+Deprecated: 2.56: Use g_data_input_stream_read_upto_finish() instead, which
+has more consistent behaviour regarding the stop character.
 
 </description>
 <parameters>
@@ -13611,6 +13712,8 @@ g_data_input_stream_read_upto() again.
 Note that @stop_chars may contain '\0' if @stop_chars_len is
 specified.
 
+The returned string will always be nul-terminated on success.
+
 Since: 2.26
 
 </description>
@@ -13712,6 +13815,8 @@ Note that this function does not consume the stop character. You
 have to use g_data_input_stream_read_byte() to get it before calling
 g_data_input_stream_read_upto_async() again.
 
+The returned string will always be nul-terminated on success.
+
 Since: 2.24
 
 </description>
@@ -14805,7 +14910,9 @@ not compatible with the D-Bus protocol, the operation fails with
 
 If @reply_type is non-%NULL then the reply will be checked for having this type and an
 error will be raised if it does not match.  Said another way, if you give a @reply_type
-then any non-%NULL return value will be of this type.
+then any non-%NULL return value will be of this type. Unless it’s
+%G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more
+values.
 
 If the @parameters #GVariant is floating, it is consumed. This allows
 convenient 'inline' use of g_variant_new(), e.g.:
@@ -14868,7 +14975,8 @@ or %NULL if not passing parameters
 </parameter_description>
 </parameter>
 <parameter name="reply_type">
-<parameter_description> the expected type of the reply, or %NULL
+<parameter_description> the expected type of the reply (which will be a
+tuple), or %NULL
 </parameter_description>
 </parameter>
 <parameter name="flags">
@@ -15311,7 +15419,9 @@ Emits a signal.
 
 If the parameters GVariant is floating, it is consumed.
 
-This can only fail if @parameters is not compatible with the D-Bus protocol.
+This can only fail if @parameters is not compatible with the D-Bus protocol
+(%G_IO_ERROR_INVALID_ARGUMENT), or if @connection has been closed
+(%G_IO_ERROR_CLOSED).
 
 Since: 2.26
 
@@ -17396,7 +17506,7 @@ emitted immediately.
 
 For example, an exported D-Bus interface may queue up property
 changes and emit the
-`org.freedesktop.DBus.Properties::PropertiesChanged`
+`org.freedesktop.DBus.Properties.PropertiesChanged`
 signal later (e.g. in an idle handler). This technique is useful
 for collapsing multiple property changes into one.
 
@@ -19339,7 +19449,7 @@ else
 g_dbus_method_invocation_return_value (invocation,
 g_variant_new (&quot;(s)&quot;, result_string));
 
-/&lt;!-- --&gt;* Do not free @invocation here; returning a value does that *&lt;!-- --&gt;/
+// Do not free @invocation here; returning a value does that
 ]|
 
 This method will take ownership of @invocation. See
@@ -20771,9 +20881,9 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A reference to the #GVariant instance that holds the value
-for @property_name or %NULL if the value is not in the cache. The
-returned reference must be freed with g_variant_unref().
+<return> A reference to the #GVariant instance
+that holds the value for @property_name or %NULL if the value is not in
+the cache. The returned reference must be freed with g_variant_unref().
 
 </return>
 </function>
@@ -20791,7 +20901,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A %NULL-terminated array of strings or %NULL if
+<return> A
+%NULL-terminated array of strings or %NULL if
 @proxy has no cached properties. Free the returned array with
 g_strfreev().
 
@@ -20871,8 +20982,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusInterfaceInfo or %NULL. Do not unref the returned
-object, it is owned by @proxy.
+<return> A #GDBusInterfaceInfo or %NULL.
+Do not unref the returned object, it is owned by @proxy.
 
 </return>
 </function>
@@ -20929,7 +21040,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> The name owner or %NULL if no name owner exists. Free with g_free().
+<return> The name owner or %NULL if no name
+owner exists. Free with g_free().
 
 </return>
 </function>
@@ -21039,7 +21151,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+<return> A #GDBusProxy or %NULL if @error is set.
+Free with g_object_unref().
 
 </return>
 </function>
@@ -21111,7 +21224,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+<return> A #GDBusProxy or %NULL if @error is set.
+Free with g_object_unref().
 
 </return>
 </function>
@@ -21160,7 +21274,8 @@ that @proxy conforms to or %NULL.
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
+<return> A #GDBusProxy or %NULL if error is set.
+Free with g_object_unref().
 
 </return>
 </function>
@@ -21223,7 +21338,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
+<return> A #GDBusProxy or %NULL if error is set.
+Free with g_object_unref().
 
 </return>
 </function>
@@ -21323,7 +21439,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 <parameter name="info">
-<parameter_description> Minimum interface this proxy conforms to or %NULL to unset.
+<parameter_description> Minimum interface this proxy conforms to
+or %NULL to unset.
 </parameter_description>
 </parameter>
 </parameters>
@@ -21690,6 +21807,32 @@ Since: 2.32
 </return>
 </function>
 
+<function name="g_desktop_app_info_get_locale_string">
+<description>
+Looks up a localized string value in the keyfile backing @info
+translated to the current locale.
+
+The @key is looked up in the &quot;Desktop Entry&quot; group.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="info">
+<parameter_description> a #GDesktopAppInfo
+</parameter_description>
+</parameter>
+<parameter name="key">
+<parameter_description> the key to look up
+</parameter_description>
+</parameter>
+</parameters>
+<return> a newly allocated string, or %NULL if the key
+is not found
+
+</return>
+</function>
+
 <function name="g_desktop_app_info_get_nodisplay">
 <description>
 Gets the value of the NoDisplay key, which helps determine if the
@@ -28971,6 +29114,30 @@ the @parse_name cannot be parsed.
 </return>
 </function>
 
+<function name="g_file_peek_path">
+<description>
+Exactly like g_file_get_path(), but caches the result via
+g_object_set_qdata_full().  This is useful for example in C
+applications which mix `g_file_*` APIs with native ones.  It
+also avoids an extra duplicated string when possible, so will be
+generally more efficient.
+
+This call does no blocking I/O.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="file">
+<parameter_description> input #GFile
+</parameter_description>
+</parameter>
+</parameters>
+<return> string containing the #GFile's path,
+or %NULL if no such path exists. The returned string is owned by @file.
+</return>
+</function>
+
 <function name="g_file_poll_mountable">
 <description>
 Polls a file of type #G_FILE_TYPE_MOUNTABLE.
@@ -29074,7 +29241,7 @@ When you are done with it, release it with g_object_unref()
 Utility function to check if a particular file exists. This is
 implemented using g_file_query_info() and as such does blocking I/O.
 
-Note that in many cases it is racy to first check for file existence
+Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use)
 and then execute something based on the outcome of that, because the
 file might have been created or removed in between the operations. The
 general approach to handling that is to not check, but just do the
@@ -33217,6 +33384,14 @@ This function is run after the module has been loaded into GIO,
 to initialize the module. Typically, this function will call
 g_io_extension_point_implement().
 
+Since 2.56, this function should be named `g_io_&lt;modulename&gt;_load`, where
+`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+everything after the first dot removed, and with `-` replaced with `_`
+throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+Using the new symbol names avoids name clashes when building modules
+statically. The old symbol names continue to be supported, but cannot be used
+for static builds.
+
 </description>
 <parameters>
 <parameter name="module">
@@ -33271,6 +33446,14 @@ When installing a module that implements g_io_module_query() you must
 run gio-querymodules in order to build the cache files required for
 lazy loading.
 
+Since 2.56, this function should be named `g_io_&lt;modulename&gt;_query`, where
+`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+everything after the first dot removed, and with `-` replaced with `_`
+throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+Using the new symbol names avoids name clashes when building modules
+statically. The old symbol names continue to be supported, but cannot be used
+for static builds.
+
 Since: 2.24
 
 </description>
@@ -33351,6 +33534,14 @@ Required API for GIO modules to implement.
 This function is run when the module is being unloaded from GIO,
 to finalize the module.
 
+Since 2.56, this function should be named `g_io_&lt;modulename&gt;_unload`, where
+`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+everything after the first dot removed, and with `-` replaced with `_`
+throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+Using the new symbol names avoids name clashes when building modules
+statically. The old symbol names continue to be supported, but cannot be used
+for static builds.
+
 </description>
 <parameters>
 <parameter name="module">
@@ -37374,7 +37565,7 @@ If no port is specified in @host_and_port then @default_port will be
 used as the port number to connect to.
 
 In general, @host_and_port is expected to be provided by the user
-(allowing them to give the hostname, and a port overide if necessary)
+(allowing them to give the hostname, and a port override if necessary)
 and @default_port is expected to be provided by the application.
 
 (The port component of @host_and_port can also be specified as a
@@ -38146,6 +38337,8 @@ Since: 2.40
 Deprecated in favor of g_notification_set_priority().
 
 Since: 2.40
+Deprecated: 2.42: Since 2.42, this has been deprecated in favour of
+g_notification_set_priority().
 
 </description>
 <parameters>
@@ -39608,6 +39801,9 @@ if @cancellable has already been cancelled when you call, which
 may happen if you call this method after a source triggers due
 to having been cancelled.
 
+Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying
+transports like D/TLS require that you send the same @buffer and @count.
+
 Virtual: write_nonblocking
 
 </description>
@@ -42699,7 +42895,7 @@ with it.
 
 <function name="g_settings_list_relocatable_schemas">
 <description>
-&lt;!-- --&gt;
+Deprecated.
 
 Since: 2.28
 
@@ -42717,7 +42913,7 @@ modified or freed.
 
 <function name="g_settings_list_schemas">
 <description>
-&lt;!-- --&gt;
+Deprecated.
 
 Since: 2.26
 
@@ -47933,6 +48129,10 @@ is helpful for determining the port number that was used for when
 requesting a binding to port 0 (ie: &quot;any port&quot;).  This address, if
 requested, belongs to the caller and must be freed.
 
+Call g_socket_listener_close() to stop listening on @address; this will not
+be done automatically when you drop your final reference to @listener, as
+references may be held internally.
+
 Since: 2.22
 
 </description>
@@ -48018,6 +48218,10 @@ to accept to identify this particular source, which is
 useful if you're listening on multiple addresses and do
 different things depending on what address is connected to.
 
+Call g_socket_listener_close() to stop listening on @port; this will not
+be done automatically when you drop your final reference to @listener, as
+references may be held internally.
+
 Since: 2.22
 
 </description>
@@ -52522,12 +52726,15 @@ known.
 
 <function name="g_tls_client_connection_get_use_ssl3">
 <description>
-Gets whether @conn will use SSL 3.0 rather than the
-highest-supported version of TLS; see
-g_tls_client_connection_set_use_ssl3().
+Gets whether @conn will force the lowest-supported TLS protocol
+version rather than attempt to negotiate the highest mutually-
+supported version of TLS; see g_tls_client_connection_set_use_ssl3().
 
 Since: 2.28
 
+Deprecated: 2.56: SSL 3.0 is insecure, and this function does not
+actually indicate whether it is enabled.
+
 </description>
 <parameters>
 <parameter name="conn">
@@ -52535,7 +52742,7 @@ Since: 2.28
 </parameter_description>
 </parameter>
 </parameters>
-<return> whether @conn will use SSL 3.0
+<return> whether @conn will use the lowest-supported TLS protocol version
 
 </return>
 </function>
@@ -52616,14 +52823,20 @@ Since: 2.28
 
 <function name="g_tls_client_connection_set_use_ssl3">
 <description>
-If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
-trying to properly negotiate the right version of TLS or SSL to use.
-This can be used when talking to servers that do not implement the
-fallbacks correctly and which will therefore fail to handshake with
-a &quot;modern&quot; TLS handshake attempt.
+If @use_ssl3 is %TRUE, this forces @conn to use the lowest-supported
+TLS protocol version rather than trying to properly negotiate the
+highest mutually-supported protocol version with the peer. This can
+be used when talking to broken TLS servers that exhibit protocol
+version intolerance.
+
+Be aware that SSL 3.0 is generally disabled by the #GTlsBackend, so
+the lowest-supported protocol version is probably not SSL 3.0.
 
 Since: 2.28
 
+Deprecated: 2.56: SSL 3.0 is insecure, and this function does not
+generally enable or disable it, despite its name.
+
 </description>
 <parameters>
 <parameter name="conn">
@@ -52631,7 +52844,7 @@ Since: 2.28
 </parameter_description>
 </parameter>
 <parameter name="use_ssl3">
-<parameter_description> whether to use SSL 3.0
+<parameter_description> whether to use the lowest-supported protocol version
 </parameter_description>
 </parameter>
 </parameters>