[glib/docgen-fixes: 14/15] docs: Use the correct sigils for pre-processor symbols

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [glib/docgen-fixes: 14/15] docs: Use the correct sigils for pre-processor symbols
Date: Mon, 2 Aug 2021 15:06:46 +0000 (UTC)

commit 4bbe7912a1f0154bd6b1bd70f72772969558222b
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Mon Aug 2 15:58:15 2021 +0100

    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:
+ *
  * |[<!-- language="C" --> 
  * 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+:
+ *
  * |[<!-- language="C" --> 
  * 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:
+ *
  * |[<!-- language="C" --> 
  * 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:
+ *
  * |[<!-- language="C" -->
  * 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:
+ *
  * |[<!-- language="C" -->
  * 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:
  * |[<!-- language="C" --> 
  *   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 ------------------------------------------ */
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]