luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-06 01:16:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

gmain: Adapt to gi-docgen comments

Browse Source 
Now that we've switched to `gi-docgen`, let's make sure our docs are
getting updated. This commit fixes most of the previous gtk-doc
references so that they now follow gi-docgen syntax.

Some exceptions are functions or types that are referenced, but are
generated by a higher level layer like `Gio`, `GObject` or `Gtk`.
This commit is contained in:
Niels De Graef 2024-08-01 18:38:57 +02:00 committed by Niels De Graef
parent 474dbd91f7
commit 10d4edea2e
2 changed files with 375 additions and 346 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

560
glib/gmain.c
View File

File diff suppressed because it is too large Load Diff

99
glib/gmain.h
View File

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