Merge branch 'dbus-name-owning-docs' into 'main'

gdbusnameowning: Convert docs to gi-docgen linking syntax

See merge request GNOME/glib!4562

gio/gdbusnameowning.c

@@ -502,22 +502,21 @@ connection_get_cb (GObject      *source_object,
 
 /**
  * g_bus_own_name_on_connection:
- * @connection: a #GDBusConnection
+ * @connection: a bus connection
  * @name: the well-known name to own
- * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
+ * @flags: a set of flags with ownership options
  * @name_acquired_handler: (nullable) (scope notified): handler to invoke when
- *   @name is acquired or %NULL
+ *   @name is acquired, or `NULL` to ignore
  * @name_lost_handler: (nullable) (scope notified): handler to invoke when @name
- *   is lost or %NULL
+ *   is lost, or `NULL` to ignore
  * @user_data: user data to pass to handlers
- * @user_data_free_func: (nullable): function for freeing @user_data or %NULL
+ * @user_data_free_func: (nullable): function for freeing @user_data
  *
- * Like g_bus_own_name() but takes a #GDBusConnection instead of a
+ * Like [func@Gio.bus_own_name] but takes a [class@Gio.DBusConnection] instead
- * #GBusType.
+ * of a [enum@Gio.BusType].
  *
  * Returns: an identifier (never 0) that can be used with
- *     g_bus_unown_name() to stop owning the name
+ *   [func@Gio.bus_unown_name] to stop owning the name
- *
  * Since: 2.26
  */
 guint
@@ -568,47 +567,48 @@ g_bus_own_name_on_connection (GDBusConnection          *connection,
  * g_bus_own_name:
  * @bus_type: the type of bus to own a name on
  * @name: the well-known name to own
- * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
+ * @flags: a set of flags with ownership options
  * @bus_acquired_handler: (nullable) (scope notified): handler to invoke when
- *   connected to the bus of type @bus_type or %NULL
+ *   connected to the bus of type @bus_type, or `NULL` to ignore
  * @name_acquired_handler: (nullable) (scope notified): handler to invoke when
- *   @name is acquired or %NULL
+ *   @name is acquired, or `NULL` to ignore
  * @name_lost_handler: (nullable) (scope notified): handler to invoke when @name
- *   is lost or %NULL
+ *   is lost, or `NULL` to ignore
  * @user_data: user data to pass to handlers
- * @user_data_free_func: (nullable): function for freeing @user_data or %NULL
+ * @user_data_free_func: (nullable): function for freeing @user_data
  *
- * Starts acquiring @name on the bus specified by @bus_type and calls
+ * Requests ownership of @name on the bus specified by @bus_type.
- * @name_acquired_handler and @name_lost_handler when the name is
+ *
- * acquired respectively lost. Callbacks will be invoked in the thread-default
+ * It asynchronously calls @name_acquired_handler and @name_lost_handler when
+ * the name is acquired and lost, respectively.
+ *
+ * Callbacks will be invoked in the thread-default
  * main context (see [method@GLib.MainContext.push_thread_default])
  * of the thread you are calling this function from.
  *
  * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
- * callbacks will be invoked after calling this function - there are three
+ * callbacks will be invoked after calling this function — there are three
  * possible cases:
  * 
- * - @name_lost_handler with a %NULL connection (if a connection to the bus
+ * - @name_lost_handler with a `NULL` connection (if a connection to the bus
- *   can't be made).
+ *   can’t be made).
- *
+ * - @bus_acquired_handler then @name_lost_handler (if the name can’t be
- * - @bus_acquired_handler then @name_lost_handler (if the name can't be
+ *   obtained).
- *   obtained)
- *
  * - @bus_acquired_handler then @name_acquired_handler (if the name was
  *   obtained).
  *
- * When you are done owning the name, just call g_bus_unown_name()
+ * When you are done owning the name, call [func@Gio.bus_unown_name] with the
- * with the owner id this function returns.
+ * owner ID this function returns.
  *
  * If the name is acquired or lost (for example another application
  * could acquire the name if you allow replacement or the application
  * currently owning the name exits), the handlers are also invoked.
- * If the #GDBusConnection that is used for attempting to own the name
+ * If the [class@Gio.DBusConnection] that is used for attempting to own the name
  * closes, then @name_lost_handler is invoked since it is no longer
  * possible for other processes to access the process.
  *
- * You cannot use g_bus_own_name() several times for the same name (unless
+ * You cannot use [func@Gio.bus_own_name] several times for the same name (unless
- * interleaved with calls to g_bus_unown_name()) - only the first call
+ * interleaved with calls to [func@Gio.bus_unown_name]) — only the first call
  * will work.
  *
  * Another guarantee is that invocations of @name_acquired_handler
@@ -617,20 +617,19 @@ g_bus_own_name_on_connection (GDBusConnection          *connection,
  * guaranteed that the next time one of the handlers is invoked, it
  * will be @name_lost_handler. The reverse is also true.
  *
- * If you plan on exporting objects (using e.g.
+ * If you plan on exporting objects (using, for example,
- * g_dbus_connection_register_object()), note that it is generally too late
+ * [method@Gio.DBusConnection.register_object]), note that it is generally too late
  * to export the objects in @name_acquired_handler. Instead, you can do this
  * in @bus_acquired_handler since you are guaranteed that this will run
  * before @name is requested from the bus.
  *
- * This behavior makes it very simple to write applications that wants
+ * This behavior makes it very simple to write applications that want
  * to [own names](dbus-name-owning.html#d-bus-name-owning) and export objects.
  * Simply register objects to be exported in @bus_acquired_handler and
  * unregister the objects (if any) in @name_lost_handler.
  *
  * Returns: an identifier (never 0) that can be used with
- *     g_bus_unown_name() to stop owning the name.
+ *   [func@Gio.bus_unown_name] to stop owning the name
- *
  * Since: 2.26
  */
 guint
@@ -802,20 +801,19 @@ bus_own_name_free_func (gpointer user_data)
  * g_bus_own_name_with_closures: (rename-to g_bus_own_name)
  * @bus_type: the type of bus to own a name on
  * @name: the well-known name to own
- * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
+ * @flags: a set of flags with ownership options
- * @bus_acquired_closure: (nullable): #GClosure to invoke when connected to
+ * @bus_acquired_closure: (nullable): closure to invoke when connected to
- *     the bus of type @bus_type or %NULL
+ *   the bus of type @bus_type, or `NULL` to ignore
- * @name_acquired_closure: (nullable): #GClosure to invoke when @name is
+ * @name_acquired_closure: (nullable): closure to invoke when @name is
- *     acquired or %NULL
+ *   acquired, or `NULL` to ignore
- * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost or
+ * @name_lost_closure: (nullable): closure to invoke when @name is lost, or
- *     %NULL
+ *   `NULL` to ignore
  *
- * Version of g_bus_own_name() using closures instead of callbacks for
+ * Version of [func@Gio.bus_own_name using closures instead of callbacks for
  * easier binding in other languages.
  *
  * Returns: an identifier (never 0) that can be used with
- *     g_bus_unown_name() to stop owning the name.
+ *   [func@Gio.bus_unown_name] to stop owning the name.
- *
  * Since: 2.26
  */
 guint
@@ -840,20 +838,19 @@ g_bus_own_name_with_closures (GBusType            bus_type,
 
 /**
  * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection)
- * @connection: a #GDBusConnection
+ * @connection: a bus connection
  * @name: the well-known name to own
- * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
+ * @flags: a set of flags with ownership options
- * @name_acquired_closure: (nullable): #GClosure to invoke when @name is
+ * @name_acquired_closure: (nullable): closure to invoke when @name is
- *     acquired or %NULL
+ *   acquired, or `NULL` to ignore
- * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost
+ * @name_lost_closure: (nullable): closure to invoke when @name is lost,
- *     or %NULL
+ *   or `NULL` to ignore
  *
- * Version of g_bus_own_name_on_connection() using closures instead of
+ * Version of [func@Gio.bus_own_name_on_connection] using closures instead of
  * callbacks for easier binding in other languages.
  *
  * Returns: an identifier (never 0) that can be used with
- *     g_bus_unown_name() to stop owning the name.
+ *   [func@Gio.bus_unown_name] to stop owning the name.
- *
  * Since: 2.26
  */
 guint
@@ -876,16 +873,17 @@ g_bus_own_name_on_connection_with_closures (GDBusConnection    *connection,
 
 /**
  * g_bus_unown_name:
- * @owner_id: an identifier obtained from g_bus_own_name()
+ * @owner_id: an identifier obtained from [func@Gio.bus_own_name]
  *
  * Stops owning a name.
  *
  * Note that there may still be D-Bus traffic to process (relating to owning
- * and unowning the name) in the current thread-default #GMainContext after
+ * and unowning the name) in the current thread-default
- * this function has returned. You should continue to iterate the #GMainContext
+ * [struct@GLib.MainContext] after this function has returned. You should
- * until the #GDestroyNotify function passed to g_bus_own_name() is called, in
+ * continue to iterate the [struct@GLib.MainContext] until the
- * order to avoid memory leaks through callbacks queued on the #GMainContext
+ * [callback@GLib.DestroyNotify] function passed to [func@Gio.bus_own_name] is
- * after it’s stopped being iterated.
+ * called, in order to avoid memory leaks through callbacks queued on the
+ * [struct@GLib.MainContext] after it’s stopped being iterated.
  *
  * Since: 2.26
  */

gio/gdbusnameowning.h

@@ -33,9 +33,9 @@ G_BEGIN_DECLS
 
 /**
  * GBusAcquiredCallback:
- * @connection: The #GDBusConnection to a message bus.
+ * @connection: the connection to a message bus
- * @name: The name that is requested to be owned.
+ * @name: the name that is requested to be owned
- * @user_data: User data passed to g_bus_own_name().
+ * @user_data: user data passed to [func@Gio.bus_own_name]
  *
  * Invoked when a connection to a message bus has been obtained.
  *
@@ -47,9 +47,10 @@ typedef void (*GBusAcquiredCallback) (GDBusConnection *connection,
 
 /**
  * GBusNameAcquiredCallback:
- * @connection: The #GDBusConnection on which to acquired the name.
+ * @connection: the connection on which to acquired the name
- * @name: The name being owned.
+ * @name: the name being owned
- * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
+ * @user_data: user data passed to [func@Gio.bus_own_name] or
+ *   [func@Gio.bus_own_name_on_connection]
  *
  * Invoked when the name is acquired.
  *
@@ -61,10 +62,11 @@ typedef void (*GBusNameAcquiredCallback) (GDBusConnection *connection,
 
 /**
  * GBusNameLostCallback:
- * @connection: The #GDBusConnection on which to acquire the name or %NULL if
+ * @connection: the connect on which to acquire the name or `NULL` if
- * the connection was disconnected.
+ *   the connection was disconnected
- * @name: The name being owned.
+ * @name: the name being owned
- * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
+ * @user_data: user data passed to [func@Gio.bus_own_name] or
+ *   [func@Gio.bus_own_name_on_connection]
  *
  * Invoked when the name is lost or @connection has been closed.
  *