From 4bbe7912a1f0154bd6b1bd70f72772969558222b Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 2 Aug 2021 15:58:15 +0100 Subject: [PATCH] docs: Use the correct sigils for pre-processor symbols And reduce the excessive whitespace in argument and return value blocks. --- glib/gmain.c | 79 ++++++++++++++++++++++++++---------------------- glib/gmessages.c | 50 +++++++++++++++++------------- glib/gthread.c | 19 ++++++------ 3 files changed, 82 insertions(+), 66 deletions(-) diff --git a/glib/gmain.c b/glib/gmain.c index 6cba3bd53..ba8e0b08c 100644 --- a/glib/gmain.c +++ b/glib/gmain.c @@ -122,7 +122,7 @@ * thread-safe. * * Each event source is assigned a priority. The default priority, - * #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. + * %G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. * Values greater than 0 denote lower priorities. Events from high priority * sources are always processed before events from lower priority sources. * @@ -5005,11 +5005,11 @@ g_timeout_source_new_seconds (guint interval) /** * g_timeout_add_full: (rename-to g_timeout_add) * @priority: the priority of the timeout source. Typically this will be in - * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. * @interval: the time between calls to the function, in milliseconds - * (1/1000ths of a second) + * (1/1000ths of a second) * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * @notify: (nullable): function to call when the timeout is removed, or %NULL * * Sets a function to be called at regular intervals, with the given @@ -5069,15 +5069,17 @@ g_timeout_add_full (gint priority, /** * g_timeout_add: * @interval: the time between calls to the function, in milliseconds - * (1/1000ths of a second) + * (1/1000ths of a second) * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * * Sets a function to be called at regular intervals, with the default - * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly - * until it returns %FALSE, at which point the timeout is automatically - * destroyed and the function will not be called again. The first call - * to the function will be at the end of the first @interval. + * priority, %G_PRIORITY_DEFAULT. + * + * The given @function is called repeatedly until it returns %G_SOURCE_REMOVE + * or %FALSE, at which point the timeout is automatically destroyed and the + * function will not be called again. The first call to the function will be + * at the end of the first @interval. * * Note that timeout functions may be delayed, due to the processing of other * event sources. Thus they should not be relied on for precise timing. @@ -5118,24 +5120,25 @@ g_timeout_add (guint32 interval, /** * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds) * @priority: the priority of the timeout source. Typically this will be in - * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. * @interval: the time between calls to the function, in seconds * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * @notify: (nullable): function to call when the timeout is removed, or %NULL * * Sets a function to be called at regular intervals, with @priority. - * The function is called repeatedly until it returns %FALSE, at which - * point the timeout is automatically destroyed and the function will - * not be called again. + * + * The function is called repeatedly until it returns %G_SOURCE_REMOVE + * or %FALSE, at which point the timeout is automatically destroyed and + * the function will not be called again. * * Unlike g_timeout_add(), this function operates at whole second granularity. * The initial starting point of the timer is determined by the implementation * and the implementation is expected to group multiple timers together so that - * they fire all at the same time. - * To allow this grouping, the @interval to the first timer is rounded - * and can deviate up to one second from the specified interval. - * Subsequent timer iterations will generally run at the specified interval. + * they fire all at the same time. To allow this grouping, the @interval to the + * first timer is rounded and can deviate up to one second from the specified + * interval. Subsequent timer iterations will generally run at the specified + * interval. * * Note that timeout functions may be delayed, due to the processing of other * event sources. Thus they should not be relied on for precise timing. @@ -5198,8 +5201,10 @@ g_timeout_add_seconds_full (gint priority, * @data: data to pass to @function * * Sets a function to be called at regular intervals with the default - * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until - * it returns %FALSE, at which point the timeout is automatically destroyed + * priority, %G_PRIORITY_DEFAULT. + * + * The function is called repeatedly until it returns %G_SOURCE_REMOVE + * or %FALSE, at which point the timeout is automatically destroyed * and the function will not be called again. * * This internally creates a main loop source using @@ -5753,18 +5758,18 @@ g_child_watch_source_new (GPid pid) /** * g_child_watch_add_full: (rename-to g_child_watch_add) * @priority: the priority of the idle source. Typically this will be in the - * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. - * @pid: process to watch. On POSIX the positive pid of a child process. On + * range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. + * @pid: process to watch. On POSIX the positive pid of a child process. On * Windows a handle for a process (which doesn't have to be a child). * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * @notify: (nullable): function to call when the idle is removed, or %NULL * * Sets a function to be called when the child indicated by @pid * exits, at the priority @priority. * * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() - * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to + * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to * the spawn function for the child watching to work. * * In many programs, you will want to call g_spawn_check_wait_status() @@ -5818,17 +5823,17 @@ g_child_watch_add_full (gint priority, /** * g_child_watch_add: - * @pid: process id to watch. On POSIX the positive pid of a child - * process. On Windows a handle for a process (which doesn't have to be - * a child). + * @pid: process id to watch. On POSIX the positive pid of a child + * process. On Windows a handle for a process (which doesn't have + * to be a child). * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * * Sets a function to be called when the child indicated by @pid - * exits, at a default priority, #G_PRIORITY_DEFAULT. + * exits, at a default priority, %G_PRIORITY_DEFAULT. * * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() - * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to + * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to * the spawn function for the child watching to work. * * Note that on platforms where #GPid must be explicitly closed @@ -5926,13 +5931,15 @@ g_idle_source_new (void) /** * g_idle_add_full: (rename-to g_idle_add) * @priority: the priority of the idle source. Typically this will be in the - * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + * range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. * @function: function to call - * @data: data to pass to @function + * @data: data to pass to @function * @notify: (nullable): function to call when the idle is removed, or %NULL * * Adds a function to be called whenever there are no higher priority - * events pending. If the function returns %FALSE it is automatically + * events pending. + * + * If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically * removed from the list of event sources and will not be called again. * * See [memory management of sources][mainloop-memory-management] for details @@ -5979,7 +5986,7 @@ g_idle_add_full (gint priority, * * Adds a function to be called whenever there are no higher priority * events pending to the default main loop. The function is given the - * default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function + * default idle priority, %G_PRIORITY_DEFAULT_IDLE. If the function * returns %FALSE it is automatically removed from the list of event * sources and will not be called again. * @@ -6035,7 +6042,7 @@ g_idle_remove_by_data (gpointer data) * * In any other case, an idle source is created to call @function and * that source is attached to @context (presumably to be run in another - * thread). The idle source is attached with #G_PRIORITY_DEFAULT + * thread). The idle source is attached with %G_PRIORITY_DEFAULT * priority. If you want a different priority, use * g_main_context_invoke_full(). * diff --git a/glib/gmessages.c b/glib/gmessages.c index e03e6e932..890751297 100644 --- a/glib/gmessages.c +++ b/glib/gmessages.c @@ -383,7 +383,7 @@ myInvalidParameterHandler(const wchar_t *expression, * @...: format string, followed by parameters to insert * into the format string (as with printf()) * - * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). + * Logs a "critical warning" (%G_LOG_LEVEL_CRITICAL). * * Critical warnings are intended to be used in the event of an error * that originated in the current process (a programmer error). @@ -794,40 +794,44 @@ g_log_set_fatal_mask (const gchar *log_domain, /** * g_log_set_handler: * @log_domain: (nullable): the log domain, or %NULL for the default "" - * application domain + * application domain * @log_levels: the log levels to apply the log handler for. - * To handle fatal and recursive messages as well, combine - * the log levels with the #G_LOG_FLAG_FATAL and - * #G_LOG_FLAG_RECURSION bit flags. + * To handle fatal and recursive messages as well, combine + * the log levels with the %G_LOG_FLAG_FATAL and + * %G_LOG_FLAG_RECURSION bit flags. * @log_func: the log handler function * @user_data: data passed to the log handler * * Sets the log handler for a domain and a set of log levels. + * * To handle fatal and recursive messages the @log_levels parameter - * must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION + * must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION * bit flags. * - * Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if + * Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if * you want to set a handler for this log level you must combine it with - * #G_LOG_FLAG_FATAL. + * %G_LOG_FLAG_FATAL. * * This has no effect if structured logging is enabled; see * [Using Structured Logging][using-structured-logging]. * * Here is an example for adding a log handler for all warning messages * in the default domain: + * * |[ * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * ]| * * This example adds a log handler for all critical messages from GTK+: + * * |[ * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * ]| * * This example adds a log handler for all messages from GLib: + * * |[ * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); @@ -847,11 +851,11 @@ g_log_set_handler (const gchar *log_domain, /** * g_log_set_handler_full: (rename-to g_log_set_handler) * @log_domain: (nullable): the log domain, or %NULL for the default "" - * application domain + * application domain * @log_levels: the log levels to apply the log handler for. - * To handle fatal and recursive messages as well, combine - * the log levels with the #G_LOG_FLAG_FATAL and - * #G_LOG_FLAG_RECURSION bit flags. + * To handle fatal and recursive messages as well, combine + * the log levels with the %G_LOG_FLAG_FATAL and + * %G_LOG_FLAG_RECURSION bit flags. * @log_func: the log handler function * @user_data: data passed to the log handler * @destroy: destroy notify for @user_data, or %NULL @@ -1419,11 +1423,11 @@ g_logv (const gchar *log_domain, /** * g_log: - * @log_domain: (nullable): the log domain, usually #G_LOG_DOMAIN, or %NULL - * for the default + * @log_domain: (nullable): the log domain, usually %G_LOG_DOMAIN, or %NULL + * for the default * @log_level: the log level, either from #GLogLevelFlags - * or a user-defined level - * @format: the message format. See the printf() documentation + * or a user-defined level + * @format: the message format. See the `printf()` documentation * @...: the parameters to insert into the format string * * Logs an error or debugging message. @@ -1611,10 +1615,12 @@ done_query: * by the key "MESSAGE", followed by a printf()-style message format, * followed by parameters to insert in the format string * - * Log a message with structured data. The message will be passed through to - * the log writer set by the application using g_log_set_writer_func(). If the - * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will - * be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns + * Log a message with structured data. + * + * The message will be passed through to the log writer set by the application + * using g_log_set_writer_func(). If the message is fatal (i.e. its log level + * is %G_LOG_LEVEL_ERROR), the program will be aborted by calling + * G_BREAKPOINT() at the end of this function. If the log writer returns * %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. * See the documentation for #GLogWriterFunc for information on chaining * writers. @@ -1648,9 +1654,10 @@ done_query: * Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by * the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), * g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including - * glib.h. + * `glib.h`. * * For example: + * * |[ * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, * "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", @@ -1671,6 +1678,7 @@ done_query: * interpreted as a string. * * For example: + * * |[ * const GLogField fields[] = { * { "MESSAGE", "This is a debug message.", -1 }, diff --git a/glib/gthread.c b/glib/gthread.c index 29216d7fd..08389468c 100644 --- a/glib/gthread.c +++ b/glib/gthread.c @@ -164,16 +164,17 @@ * G_LOCK_DEFINE: * @name: the name of the lock * - * The #G_LOCK_ macros provide a convenient interface to #GMutex. - * #G_LOCK_DEFINE defines a lock. It can appear in any place where + * The `G_LOCK_` macros provide a convenient interface to #GMutex. + * %G_LOCK_DEFINE defines a lock. It can appear in any place where * variable definitions may appear in programs, i.e. in the first block * of a function or outside of functions. The @name parameter will be * mangled to get the name of the #GMutex. This means that you * can use names of existing variables as the parameter - e.g. the name * of the variable you intend to protect with the lock. Look at our - * give_me_next_number() example using the #G_LOCK macros: + * give_me_next_number() example using the `G_LOCK` macros: + * + * Here is an example for using the `G_LOCK` convenience macros: * - * Here is an example for using the #G_LOCK convenience macros: * |[ * G_LOCK_DEFINE (current_number); * @@ -196,14 +197,14 @@ * G_LOCK_DEFINE_STATIC: * @name: the name of the lock * - * This works like #G_LOCK_DEFINE, but it creates a static object. + * This works like %G_LOCK_DEFINE, but it creates a static object. */ /** * G_LOCK_EXTERN: * @name: the name of the lock * - * This declares a lock, that is defined with #G_LOCK_DEFINE in another + * This declares a lock, that is defined with %G_LOCK_DEFINE in another * module. */ @@ -212,7 +213,7 @@ * @name: the name of the lock * * Works like g_mutex_lock(), but for a lock defined with - * #G_LOCK_DEFINE. + * %G_LOCK_DEFINE. */ /** @@ -220,7 +221,7 @@ * @name: the name of the lock * * Works like g_mutex_trylock(), but for a lock defined with - * #G_LOCK_DEFINE. + * %G_LOCK_DEFINE. * * Returns: %TRUE, if the lock could be locked. */ @@ -230,7 +231,7 @@ * @name: the name of the lock * * Works like g_mutex_unlock(), but for a lock defined with - * #G_LOCK_DEFINE. + * %G_LOCK_DEFINE. */ /* GMutex Documentation {{{1 ------------------------------------------ */