[glib: 1/2] gdbus: Add various missing (nullable) or (not nullable) annotations

[Philip Withnall <pwithnall src gnome org>]

commit ac8f4a0db53d84c3ef5c59dd0307643cf534a459
Author: Philip Withnall <pwithnall endlessos org>
Date:   Thu May 27 15:06:05 2021 +0100

    gdbus: Add various missing (nullable) or (not nullable) annotations
    
    This is the result of checking each `Returns:` line in these files. I’ve
    only considered nullability and not other (potentially missing or
    incorrect) annotations.
    
    Including suggestions by Simon McVittie.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Helps: #2227

 gio/gdbusintrospection.c       | 14 +++++++-------
 gio/gdbusmessage.c             |  6 ++++--
 gio/gdbusobjectmanager.c       |  4 ++--
 gio/gdbusobjectmanagerserver.c |  2 +-
 gio/gdbusproxy.c               | 12 ++++++++----
 gio/gdbusserver.c              |  8 +++++---
 6 files changed, 27 insertions(+), 19 deletions(-)
---
diff --git a/gio/gdbusintrospection.c b/gio/gdbusintrospection.c
index f35b2fb44..d6aa445d5 100644
--- a/gio/gdbusintrospection.c
+++ b/gio/gdbusintrospection.c
@@ -98,7 +98,7 @@ typedef struct
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  *
  * Since: 2.26
  */
@@ -118,7 +118,7 @@ g_dbus_node_info_ref (GDBusNodeInfo *info)
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  *
  * Since: 2.26
  */
@@ -138,7 +138,7 @@ g_dbus_interface_info_ref (GDBusInterfaceInfo *info)
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  *
  * Since: 2.26
  */
@@ -158,7 +158,7 @@ g_dbus_method_info_ref (GDBusMethodInfo *info)
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  *
  * Since: 2.26
  */
@@ -178,7 +178,7 @@ g_dbus_signal_info_ref (GDBusSignalInfo *info)
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  *
  * Since: 2.26
  */
@@ -198,7 +198,7 @@ g_dbus_property_info_ref (GDBusPropertyInfo *info)
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  *
  * Since: 2.26
  */
@@ -218,7 +218,7 @@ g_dbus_arg_info_ref (GDBusArgInfo *info)
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  *
  * Since: 2.26
  */
diff --git a/gio/gdbusmessage.c b/gio/gdbusmessage.c
index bc9386ee7..e36d1fe88 100644
--- a/gio/gdbusmessage.c
+++ b/gio/gdbusmessage.c
@@ -3216,7 +3216,9 @@ g_dbus_message_set_error_name (GDBusMessage  *message,
  *
  * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
  *
- * Returns: The value.
+ * This will always be non-%NULL, but may be an empty string.
+ *
+ * Returns: (not nullable): The value.
  *
  * Since: 2.26
  */
@@ -3488,7 +3490,7 @@ _sort_keys_func (gconstpointer a,
  *   fd 12: 
dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
  * ]|
  *
- * Returns: A string that should be freed with g_free().
+ * Returns: (not nullable): A string that should be freed with g_free().
  *
  * Since: 2.26
  */
diff --git a/gio/gdbusobjectmanager.c b/gio/gdbusobjectmanager.c
index 87634cd83..169e7d16f 100644
--- a/gio/gdbusobjectmanager.c
+++ b/gio/gdbusobjectmanager.c
@@ -213,7 +213,7 @@ g_dbus_object_manager_get_objects (GDBusObjectManager *manager)
  *
  * Gets the #GDBusObjectProxy at @object_path, if any.
  *
- * Returns: (transfer full): A #GDBusObject or %NULL. Free with
+ * Returns: (transfer full) (nullable): A #GDBusObject or %NULL. Free with
  *   g_object_unref().
  *
  * Since: 2.30
@@ -236,7 +236,7 @@ g_dbus_object_manager_get_object (GDBusObjectManager *manager,
  * Gets the interface proxy for @interface_name at @object_path, if
  * any.
  *
- * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
+ * Returns: (transfer full) (nullable): A #GDBusInterface instance or %NULL. Free
  *   with g_object_unref().
  *
  * Since: 2.30
diff --git a/gio/gdbusobjectmanagerserver.c b/gio/gdbusobjectmanagerserver.c
index 0a0cea84a..a68594765 100644
--- a/gio/gdbusobjectmanagerserver.c
+++ b/gio/gdbusobjectmanagerserver.c
@@ -318,7 +318,7 @@ g_dbus_object_manager_server_set_connection (GDBusObjectManagerServer  *manager,
  *
  * Gets the #GDBusConnection used by @manager.
  *
- * Returns: (transfer full): A #GDBusConnection object or %NULL if
+ * Returns: (transfer full) (nullable): A #GDBusConnection object or %NULL if
  *   @manager isn't exported on a connection. The returned object should
  *   be freed with g_object_unref().
  *
diff --git a/gio/gdbusproxy.c b/gio/gdbusproxy.c
index 09b3a6584..a93f32304 100644
--- a/gio/gdbusproxy.c
+++ b/gio/gdbusproxy.c
@@ -2246,7 +2246,7 @@ g_dbus_proxy_new_for_bus_sync (GBusType             bus_type,
  *
  * Gets the connection @proxy is for.
  *
- * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
+ * Returns: (transfer none) (not nullable): A #GDBusConnection owned by @proxy. Do not free.
  *
  * Since: 2.26
  */
@@ -2280,7 +2280,11 @@ g_dbus_proxy_get_flags (GDBusProxy *proxy)
  *
  * Gets the name that @proxy was constructed for.
  *
- * Returns: A string owned by @proxy. Do not free.
+ * When connected to a message bus, this will usually be non-%NULL.
+ * However, it may be %NULL for a proxy that communicates using a peer-to-peer
+ * pattern.
+ *
+ * Returns: (nullable): A string owned by @proxy. Do not free.
  *
  * Since: 2.26
  */
@@ -2324,7 +2328,7 @@ g_dbus_proxy_get_name_owner (GDBusProxy *proxy)
  *
  * Gets the object path @proxy is for.
  *
- * Returns: A string owned by @proxy. Do not free.
+ * Returns: (not nullable): A string owned by @proxy. Do not free.
  *
  * Since: 2.26
  */
@@ -2341,7 +2345,7 @@ g_dbus_proxy_get_object_path (GDBusProxy *proxy)
  *
  * Gets the D-Bus interface name @proxy is for.
  *
- * Returns: A string owned by @proxy. Do not free.
+ * Returns: (not nullable): A string owned by @proxy. Do not free.
  *
  * Since: 2.26
  */
diff --git a/gio/gdbusserver.c b/gio/gdbusserver.c
index e3a436fbb..4a7303014 100644
--- a/gio/gdbusserver.c
+++ b/gio/gdbusserver.c
@@ -542,7 +542,9 @@ g_dbus_server_new_sync (const gchar        *address,
  * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
  * string that can be used by clients to connect to @server.
  *
- * Returns: A D-Bus address string. Do not free, the string is owned
+ * This is valid and non-empty if initializing the #GDBusServer succeeded.
+ *
+ * Returns: (not nullable): A D-Bus address string. Do not free, the string is owned
  * by @server.
  *
  * Since: 2.26
@@ -558,9 +560,9 @@ g_dbus_server_get_client_address (GDBusServer *server)
  * g_dbus_server_get_guid:
  * @server: A #GDBusServer.
  *
- * Gets the GUID for @server.
+ * Gets the GUID for @server, as provided to g_dbus_server_new_sync().
  *
- * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
+ * Returns: (not nullable): A D-Bus GUID. Do not free this string, it is owned by @server.
  *
  * Since: 2.26
  */