Merge branch 'nielsdg/gmain-gi-docgen' into 'main'

gmain: Adapt to gi-docgen comments

See merge request GNOME/glib!4177

glib/gmain.h

@@ -48,8 +48,8 @@ typedef enum /*< flags >*/
  * `g_main_context_{prepare,query,check,dispatch}` to integrate GMainContext in
  * other event loops.
  *
- * Flags to pass to g_main_context_new_with_flags() which affect the behaviour
- * of a #GMainContext.
+ * Flags to pass to [ctor@GLib.MainContext.new_with_flags] which affect the
+ * behaviour of a [struct@GLib.MainContext].
  *
  * Since: 2.72
  */
@@ -121,15 +121,17 @@ typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
  *     %TRUE in either its @prepare or its @check function, or if a ready time
  *     has been reached. The @dispatch function receives a callback function and
  *     user data. The callback function may be %NULL if the source was never
- *     connected to a callback using g_source_set_callback(). The @dispatch
- *     function should call the callback function with @user_data and whatever
- *     additional parameters are needed for this type of event source. The
- *     return value of the @dispatch function should be %G_SOURCE_REMOVE if the
- *     source should be removed or %G_SOURCE_CONTINUE to keep it.
+ *     connected to a callback using [method@GLib.Source.set_callback]. The
+ *     @dispatch function should call the callback function with @user_data and
+ *     whatever additional parameters are needed for this type of event source.
+ *     The return value of the @dispatch function should be
+ *     [const@GLib.SOURCE_REMOVE] if the source should be removed or
+ *     [const@GLib.SOURCE_CONTINUE] to keep it.
  * @finalize: Called when the source is finalized. At this point, the source
  *     will have been destroyed, had its callback cleared, and have been removed
- *     from its #GMainContext, but it will still have its final reference count,
- *     so methods can be called on it from within this function.
+ *     from its [struct@GLib.MainContext], but it will still have its final
+ *     reference count, so methods can be called on it from within this
+ *     function.
  *
  * The `GSourceFuncs` struct contains a table of
  * functions used to handle event sources in a generic manner.
@@ -182,15 +184,17 @@ typedef struct _GSourceFuncs            GSourceFuncs;
  * @user_data: data passed to the function, set when the source was
  *     created with one of the above functions
  *
- * Specifies the type of function passed to g_timeout_add(),
- * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
+ * Specifies the type of function passed to [func@GLib.timeout_add],
+ * [func@GLib.timeout_add_full], [func@GLib.idle_add], and
+ * [func@GLib.idle_add_full].
  *
- * When calling g_source_set_callback(), you may need to cast a function of a
- * different type to this type. Use G_SOURCE_FUNC() to avoid warnings about
- * incompatible function types.
+ * When calling [method@GLib.Source.set_callback], you may need to cast a
+ * function of a different type to this type. Use [func@GLib.SOURCE_FUNC] to
+ * avoid warnings about incompatible function types.
  *
- * Returns: %FALSE if the source should be removed. %G_SOURCE_CONTINUE and
- * %G_SOURCE_REMOVE are more memorable names for the return value.
+ * Returns: %FALSE if the source should be removed.
+ * [const@GLib.SOURCE_CONTINUE] and [const@GLib.SOURCE_REMOVE] are more
+ * memorable names for the return value.
  */
 typedef gboolean (*GSourceFunc)       (gpointer user_data);
 
@@ -202,7 +206,7 @@ typedef gboolean (*GSourceFunc)       (gpointer user_data);
  * A source function that is only called once before being removed from the main
  * context automatically.
  *
- * See: g_idle_add_once(), g_timeout_add_once()
+ * See: [func@GLib.idle_add_once], [func@GLib.timeout_add_once]
  *
  * Since: 2.74
  */
@@ -212,15 +216,16 @@ typedef void (* GSourceOnceFunc) (gpointer user_data);
  * G_SOURCE_FUNC:
  * @f: a function pointer.
  *
- * Cast a function pointer to a #GSourceFunc, suppressing warnings from GCC 8
- * onwards with `-Wextra` or `-Wcast-function-type` enabled about the function
- * types being incompatible.
+ * Cast a function pointer to a [callback@GLib.SourceFunc], suppressing
+ * warnings from GCC 8 onwards with `-Wextra` or `-Wcast-function-type` enabled
+ * about the function types being incompatible.
  *
  * For example, the correct type of callback for a source created by
- * g_child_watch_source_new() is #GChildWatchFunc, which accepts more arguments
- * than #GSourceFunc. Casting the function with `(GSourceFunc)` to call
- * g_source_set_callback() will trigger a warning, even though it will be cast
- * back to the correct type before it is called by the source.
+ * [func@GLib.child_watch_source_new] is #GChildWatchFunc, which accepts more
+ * arguments than [callback@GLib.SourceFunc]. Casting the function with
+ * `(GSourceFunc)` to call [method@GLib.Source.set_callback] will trigger a
+ * warning, even though it will be cast back to the correct type before it is
+ * called by the source.
  *
  * Since: 2.58
  */
@@ -231,13 +236,13 @@ typedef void (* GSourceOnceFunc) (gpointer user_data);
  * @pid: the process id of the child process
  * @wait_status: Status information about the child process, encoded
  *               in a platform-specific manner
- * @user_data: user data passed to g_child_watch_add()
+ * @user_data: user data passed to [func@GLib.child_watch_add]
  *
  * Prototype of a #GChildWatchSource callback, called when a child
  * process has exited.
  *
- * To interpret @wait_status, see the documentation
- * for g_spawn_check_wait_status(). In particular,
+ * To interpret @wait_status, see the documentation for
+ * [func@GLib.spawn_check_wait_status]. In particular,
  * on Unix platforms, note that it is usually not equal
  * to the integer passed to `exit()` or returned from `main()`.
  */
@@ -250,8 +255,8 @@ typedef void     (*GChildWatchFunc)   (GPid     pid,
  * GSourceDisposeFunc:
  * @source: #GSource that is currently being disposed
  *
- * Dispose function for @source. See g_source_set_dispose_function() for
- * details.
+ * Dispose function for @source. See [method@GLib.Source.set_dispose_function]
+ * for details.
  *
  * Since: 2.64
  */
@@ -420,7 +425,7 @@ struct _GSourceFuncs
  * Use this for default priority event sources.
  *
  * In GLib this priority is used when adding timeout functions
- * with g_timeout_add(). In GDK this priority is used for events
+ * with [func@GLib.timeout_add]. In GDK this priority is used for events
  * from the X server.
  */
 #define G_PRIORITY_DEFAULT          0
@@ -443,7 +448,7 @@ struct _GSourceFuncs
  * Use this for default priority idle functions.
  *
  * In GLib this priority is used when adding idle functions with
- * g_idle_add().
+ * [func@GLib.idle_add].
  */
 #define G_PRIORITY_DEFAULT_IDLE     200
 
@@ -459,8 +464,8 @@ struct _GSourceFuncs
 /**
  * G_SOURCE_REMOVE:
  *
- * Use this macro as the return value of a #GSourceFunc to remove
- * the #GSource from the main loop.
+ * Use this macro as the return value of a [callback@GLib.SourceFunc] to remove
+ * the [struct@GLib.Source] from the main loop.
  *
  * Since: 2.32
  */
@@ -469,8 +474,8 @@ struct _GSourceFuncs
 /**
  * G_SOURCE_CONTINUE:
  *
- * Use this macro as the return value of a #GSourceFunc to leave
- * the #GSource in the main loop.
+ * Use this macro as the return value of a [callback@GLib.SourceFunc] to leave
+ * the [struct@GLib.Source] in the main loop.
  *
  * Since: 2.32
  */
@@ -588,13 +593,13 @@ typedef void GMainContextPusher GLIB_AVAILABLE_TYPE_IN_2_64;
  * @main_context: (transfer none): a main context to push
  *
  * Push @main_context as the new thread-default main context for the current
- * thread, using g_main_context_push_thread_default(), and return a new
- * #GMainContextPusher. Pop with g_main_context_pusher_free(). Using
- * g_main_context_pop_thread_default() on @main_context while a
- * #GMainContextPusher exists for it can lead to undefined behaviour.
+ * thread, using [method@GLib.MainContext.push_thread_default], and return a
+ * new [alias@GLib.MainContextPusher]. Pop with g_main_context_pusher_free().
+ * Using [method@GLib.MainContext.pop_thread_default] on @main_context while a
+ * [alias@GLib.MainContextPusher] exists for it can lead to undefined behaviour.
  *
- * Using two #GMainContextPushers in the same scope is not allowed, as it leads
- * to an undefined pop order.
+ * Using two [alias@GLib.MainContextPusher]s in the same scope is not allowed,
+ * as it leads to an undefined pop order.
  *
  * This is intended to be used with g_autoptr().  Note that g_autoptr()
  * is only available when using GCC or clang, so the following example
@@ -645,8 +650,8 @@ G_GNUC_END_IGNORE_DEPRECATIONS
  * Pop @pusher’s main context as the thread default main context.
  * See g_main_context_pusher_new() for details.
  *
- * This will pop the #GMainContext as the current thread-default main context,
- * but will not call g_main_context_unref() on it.
+ * This will pop the [struct@GLib.MainContext] as the current thread-default
+ * main context, but will not call [method@GLib.MainContext.unref] on it.
  *
  * Since: 2.64
  */
@@ -833,10 +838,10 @@ gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
  * GClearHandleFunc:
  * @handle_id: the handle ID to clear
  *
- * Specifies the type of function passed to g_clear_handle_id().
- * The implementation is expected to free the resource identified
- * by @handle_id; for instance, if @handle_id is a #GSource ID,
- * g_source_remove() can be used.
+ * Specifies the type of function passed to [func@GLib.clear_handle_id] The
+ * implementation is expected to free the resource identified by @handle_id;
+ * for instance, if @handle_id is a [struct@GLib.Source] ID,
+ * [func@GLib.Source.remove] can be used.
  *
  * Since: 2.56
  */