mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-01-26 22:16:16 +01:00
docs: Use the correct sigils for pre-processor symbols
And reduce the excessive whitespace in argument and return value blocks.
This commit is contained in:
Emmanuele Bassi
parent
97a6111c83
commit
4bbe7912a1
79
glib/gmain.c
79
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().
|
||||
*
|
||||
|
||||
@ -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 },
|
||||
|
||||
@ -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 ------------------------------------------ */
|
||||
|
||||
Loading…
Reference in New Issue
Block a user