From e9d05783f6a23965ae2344c36d33e2cb87bfec10 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 1 Oct 2001 22:54:48 +0000 Subject: [PATCH] More markup fixes and completions. * glib/tmpl/iochannels.sgml, glib/tmpl/shell.sgml, glib/tmpl/spawn.sgml, glib/tmpl/memory.sgml, glib/tmpl/macros.sgml, glib/tmpl/completion.sgml, glib/tmpl/main.sgml, glib/tmpl/messages.sgml, glib/tmpl/misc_utils.sgml, glib/tmpl/threads.sgml, glib/tmpl/trees-nary.sgml, glib/tmpl/string_utils.sgml: More markup fixes and completions. --- docs/reference/ChangeLog | 10 + docs/reference/glib/tmpl/completion.sgml | 2 +- docs/reference/glib/tmpl/iochannels.sgml | 34 ++-- docs/reference/glib/tmpl/macros.sgml | 2 +- docs/reference/glib/tmpl/main.sgml | 43 ++--- docs/reference/glib/tmpl/memory.sgml | 2 +- docs/reference/glib/tmpl/messages.sgml | 6 +- docs/reference/glib/tmpl/misc_utils.sgml | 2 +- docs/reference/glib/tmpl/shell.sgml | 12 +- docs/reference/glib/tmpl/spawn.sgml | 46 ++--- docs/reference/glib/tmpl/string_utils.sgml | 46 ++--- docs/reference/glib/tmpl/threads.sgml | 296 +++++++++++++++-------------- docs/reference/glib/tmpl/trees-nary.sgml | 2 +- 13 files changed, 260 insertions(+), 243 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 57425ca..ba27bd6 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,13 @@ +2001-10-01 Matthias Clasen + + * glib/tmpl/iochannels.sgml, glib/tmpl/shell.sgml, + glib/tmpl/spawn.sgml, glib/tmpl/memory.sgml, + glib/tmpl/macros.sgml, glib/tmpl/completion.sgml, + glib/tmpl/main.sgml, glib/tmpl/messages.sgml, + glib/tmpl/misc_utils.sgml, glib/tmpl/threads.sgml, + glib/tmpl/trees-nary.sgml, glib/tmpl/string_utils.sgml: + More markup fixes and completions. + Mon Oct 1 15:59:46 2001 Owen Taylor * glib/tmpl/strings.sgml docs/glib-sections.txt: Rename diff --git a/docs/reference/glib/tmpl/completion.sgml b/docs/reference/glib/tmpl/completion.sgml index 5fb26bf..f91b65c 100644 --- a/docs/reference/glib/tmpl/completion.sgml +++ b/docs/reference/glib/tmpl/completion.sgml @@ -38,7 +38,7 @@ The data structure used for automatic completion. items is the list of target items (strings or data structures). func is the function called to get the string -associated with a target item. It is NULL if the target items are strings. +associated with a target item. It is %NULL if the target items are strings. prefix is the last prefix passed to g_completion_complete(). cache is the list of items which begin with diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml index 604262b..19b582f 100644 --- a/docs/reference/glib/tmpl/iochannels.sgml +++ b/docs/reference/glib/tmpl/iochannels.sgml @@ -276,32 +276,34 @@ operation. - +Stati returned by most of the #GIOFuncs functions. -@G_IO_STATUS_ERROR: -@G_IO_STATUS_NORMAL: -@G_IO_STATUS_EOF: -@G_IO_STATUS_AGAIN: +@G_IO_STATUS_ERROR: An error occurred. +@G_IO_STATUS_NORMAL: Success. +@G_IO_STATUS_EOF: End of file. +@G_IO_STATUS_AGAIN: Resource temporarily unavailable. - +Error codes returned by #GIOChannel operations. -@G_IO_CHANNEL_ERROR_FBIG: -@G_IO_CHANNEL_ERROR_INVAL: -@G_IO_CHANNEL_ERROR_IO: -@G_IO_CHANNEL_ERROR_ISDIR: -@G_IO_CHANNEL_ERROR_NOSPC: -@G_IO_CHANNEL_ERROR_NXIO: +@G_IO_CHANNEL_ERROR_FBIG: File too large. +@G_IO_CHANNEL_ERROR_INVAL: Invalid argument. +@G_IO_CHANNEL_ERROR_IO: IO error. +@G_IO_CHANNEL_ERROR_ISDIR: File is a directory. +@G_IO_CHANNEL_ERROR_NOSPC: No space left on device. +@G_IO_CHANNEL_ERROR_NXIO: No such device or address. @G_IO_CHANNEL_ERROR_OVERFLOW: -@G_IO_CHANNEL_ERROR_PIPE: -@G_IO_CHANNEL_ERROR_FAILED: +@G_IO_CHANNEL_ERROR_PIPE: Broken pipe. +@G_IO_CHANNEL_ERROR_FAILED: Some other error. - +Error domain for #GIOChannel operations. Errors in this domain will +be from the #IOChannelError enumeration. See #GError for information on +error domains. @@ -444,7 +446,7 @@ g_io_add_watch_full(), which is called when the requested condition on a @source: the #GIOChannel event source. @condition: the condition which has been satisfied. @data: user data set in g_io_add_watch() or g_io_add_watch_full(). -@Returns: the function should return FALSE if the event source should be +@Returns: the function should return %FALSE if the event source should be removed. diff --git a/docs/reference/glib/tmpl/macros.sgml b/docs/reference/glib/tmpl/macros.sgml index eee66d4..4912c67 100644 --- a/docs/reference/glib/tmpl/macros.sgml +++ b/docs/reference/glib/tmpl/macros.sgml @@ -62,7 +62,7 @@ UNIX-specific code in "#ifdef G_OS_UNIX". Checks the version of the GLib library. -It returns TRUE if the GLib library is the same or newer than the given +It returns %TRUE if the GLib library is the same or newer than the given version. diff --git a/docs/reference/glib/tmpl/main.sgml b/docs/reference/glib/tmpl/main.sgml index a411757..d70a1be 100644 --- a/docs/reference/glib/tmpl/main.sgml +++ b/docs/reference/glib/tmpl/main.sgml @@ -176,8 +176,8 @@ Creates a new #GMainLoop for the default main loop. A compatibility macro, see g_main_loop_new(). -@is_running: set to TRUE to indicate that the loop is running. This is not -very important since calling g_main_run() will set this to TRUE anyway. +@is_running: set to %TRUE to indicate that the loop is running. This is not +very important since calling g_main_run() will set this to %TRUE anyway. @Returns: a new #GMainLoop. @@ -316,11 +316,11 @@ Runs a single iteration for the default #GMainContext. A compatibility macro, see g_main_context_iteration(). -@may_block: set to TRUE if it should block (i.e. wait) until an event source +@may_block: set to %TRUE if it should block (i.e. wait) until an event source becomes ready. It will return after an event source has been processed. -If set to FALSE it will return immediately if no event source is ready to be +If set to %FALSE it will return immediately if no event source is ready to be processed. -@Returns: TRUE if more events are pending. +@Returns: %TRUE if more events are pending. @@ -573,8 +573,6 @@ g_main_context_set_poll_func() for full details. @data: @notify: @Returns: - -@destroy: @@ -609,7 +607,7 @@ you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use #gushort revents; a bitwise combination of flags from #GIOCondition, returned from the -poll() function to indicate which events occurred. +poll() function to indicate which events occurred. @@ -680,25 +678,26 @@ Called when the source is destroyed. -For idle sources, the prepare and check functions always return TRUE to +For idle sources, the prepare and check functions always return %TRUE to indicate that the source is always ready to be processed. The prepare function also returns a timeout value of 0 to ensure that the -poll() call doesn't block (since that would be time wasted which could have -been spent running the idle function). +poll() call doesn't block (since that would be time +wasted which could have been spent running the idle function). -For timeout sources, the prepare and check functions both return TRUE if the -timeout interval has expired. -The prepare function also returns a timeout value to ensure that the poll() -call doesn't block too long and miss the next timeout. +For timeout sources, the prepare and check functions both return %TRUE if the +timeout interval has expired. The prepare function also returns a timeout +value to ensure that the poll() call doesn't block too +long and miss the next timeout. -For file descriptor sources, the prepare function typically returns FALSE, -since it must wait until poll() has been called before it knows whether any -events need to be processed. It sets the returned timeout to -1 to indicate -that it doesn't mind how long the poll() call blocks. -In the check function, it tests the results of the poll() call to see if -the required condition has been met, and returns TRUE if so. +For file descriptor sources, the prepare function typically returns %FALSE, +since it must wait until poll() has been called before +it knows whether any events need to be processed. It sets the returned +timeout to -1 to indicate that it doesn't mind how long the +poll() call blocks. +In the check function, it tests the results of the poll() +call to see if the required condition has been met, and returns %TRUE if so. @prepare: @@ -842,7 +841,7 @@ g_idle_add(), and g_idle_add_full(). @data: data passed to the function, set when the source was created with one of the above functions. -@Returns: it should return FALSE if the source should be removed. +@Returns: it should return %FALSE if the source should be removed. diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml index 3942db7..1b932b7 100644 --- a/docs/reference/glib/tmpl/memory.sgml +++ b/docs/reference/glib/tmpl/memory.sgml @@ -154,7 +154,7 @@ from @mem. If @mem is %NULL it returns %NULL. @mem: the memory to copy. @byte_size: the number of bytes to copy. -@Returns: a pointer to the newly allocated copy of the memory, or %NULL if @mem +@Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem is %NULL. diff --git a/docs/reference/glib/tmpl/messages.sgml b/docs/reference/glib/tmpl/messages.sgml index 8487aa7..bdafb4b 100644 --- a/docs/reference/glib/tmpl/messages.sgml +++ b/docs/reference/glib/tmpl/messages.sgml @@ -23,7 +23,7 @@ These can be extended with user-defined levels. Defines the log domain. -For applications, this is typically left as the default NULL (or "") domain. +For applications, this is typically left as the default %NULL (or "") domain. Libraries should define this so that any messages which they log can be differentiated from messages from other libraries and application code. But be careful not to define it in any public header files. @@ -181,10 +181,10 @@ to set a handler for this log level you must combine it with G_LOG_FLAG_FATAL. -@log_domain: the log domain, or NULL for the default "" application domain. +@log_domain: the log domain, or %NULL for the default "" 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_RECURSIVE bit flags. +#G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSIVE bit flags. @log_func: the log handler function. @user_data: data passed to the log handler. @Returns: the id of the new handler. diff --git a/docs/reference/glib/tmpl/misc_utils.sgml b/docs/reference/glib/tmpl/misc_utils.sgml index 08d42d5..2b38926 100644 --- a/docs/reference/glib/tmpl/misc_utils.sgml +++ b/docs/reference/glib/tmpl/misc_utils.sgml @@ -127,7 +127,7 @@ or 'C:/windows' on windows systems. @file_name: a file name. -@Returns: TRUE if @file_name is an absolute path. +@Returns: %TRUE if @file_name is an absolute path. diff --git a/docs/reference/glib/tmpl/shell.sgml b/docs/reference/glib/tmpl/shell.sgml index 9e8dcdd..6a519f4 100644 --- a/docs/reference/glib/tmpl/shell.sgml +++ b/docs/reference/glib/tmpl/shell.sgml @@ -16,16 +16,18 @@ Shell-related Utilities - +Error codes returned by shell functions. -@G_SHELL_ERROR_BAD_QUOTING: -@G_SHELL_ERROR_EMPTY_STRING: -@G_SHELL_ERROR_FAILED: +@G_SHELL_ERROR_BAD_QUOTING: Mismatched or otherwise mangled quoting. +@G_SHELL_ERROR_EMPTY_STRING: String to be parsed was empty. +@G_SHELL_ERROR_FAILED: Some other error. - +Error domain for shell functions. Errors in this domain will +be from the #GShellError enumeration. See #GError for information on +error domains. diff --git a/docs/reference/glib/tmpl/spawn.sgml b/docs/reference/glib/tmpl/spawn.sgml index 358cce6..2e213d3 100644 --- a/docs/reference/glib/tmpl/spawn.sgml +++ b/docs/reference/glib/tmpl/spawn.sgml @@ -16,33 +16,35 @@ Spawning Processes (fork/exec) - +Error codes returned by spawning processes. -@G_SPAWN_ERROR_FORK: -@G_SPAWN_ERROR_READ: -@G_SPAWN_ERROR_CHDIR: -@G_SPAWN_ERROR_ACCES: -@G_SPAWN_ERROR_PERM: -@G_SPAWN_ERROR_2BIG: -@G_SPAWN_ERROR_NOEXEC: -@G_SPAWN_ERROR_NAMETOOLONG: -@G_SPAWN_ERROR_NOENT: -@G_SPAWN_ERROR_NOMEM: -@G_SPAWN_ERROR_NOTDIR: -@G_SPAWN_ERROR_LOOP: -@G_SPAWN_ERROR_TXTBUSY: -@G_SPAWN_ERROR_IO: -@G_SPAWN_ERROR_NFILE: -@G_SPAWN_ERROR_MFILE: -@G_SPAWN_ERROR_INVAL: -@G_SPAWN_ERROR_ISDIR: -@G_SPAWN_ERROR_LIBBAD: -@G_SPAWN_ERROR_FAILED: +@G_SPAWN_ERROR_FORK: Fork failed due to lack of memory. +@G_SPAWN_ERROR_READ: Read or select on pipes failed. +@G_SPAWN_ERROR_CHDIR: Changing to working directory failed. +@G_SPAWN_ERROR_ACCES: execv() returned %EACCES. +@G_SPAWN_ERROR_PERM: execv() returned %EPERM. +@G_SPAWN_ERROR_2BIG: execv() returned %E2BIG. +@G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC. +@G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG. +@G_SPAWN_ERROR_NOENT: execv() returned %ENOENT. +@G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM. +@G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR. +@G_SPAWN_ERROR_LOOP: execv() returned %ELOOP. +@G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY. +@G_SPAWN_ERROR_IO: execv() returned %EIO. +@G_SPAWN_ERROR_NFILE: execv() returned %ENFILE. +@G_SPAWN_ERROR_MFILE: execv() returned %EMFILE. +@G_SPAWN_ERROR_INVAL: execv() returned %EINVAL. +@G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR. +@G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD. +@G_SPAWN_ERROR_FAILED: Some other fatal failure, error->message should explain. - +Error domain for spawning processes. Errors in this domain will +be from the #GSpawnError enumeration. See #GError for information on +error domains. diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml index 9e74424..11d3719 100644 --- a/docs/reference/glib/tmpl/string_utils.sgml +++ b/docs/reference/glib/tmpl/string_utils.sgml @@ -28,15 +28,15 @@ The returned string should be freed when no longer needed. Duplicates the first @n characters of a string, returning a newly-allocated -buffer @n + 1 characters long which will always be null-terminated. -If @str is less than @n characters long the buffer is padded with nulls. +buffer @n + 1 characters long which will always be nul-terminated. +If @str is less than @n characters long the buffer is padded with nuls. The returned value should be freed when no longer needed. @str: the string to duplicate part of. @n: the maximum number of characters to copy from @str. @Returns: a newly-allocated buffer containing the first @n characters of @str, -null-terminated. +nul-terminated. @@ -165,7 +165,7 @@ The returned string should be freed when no longer needed. A safer form of the standard sprintf() function. The output is guaranteed to not exceed @n characters (including the -terminating NULL character), so it is easy to ensure that a buffer overflow +terminating nul character), so it is easy to ensure that a buffer overflow cannot occur. @@ -174,7 +174,7 @@ See also g_strdup_printf(). In versions of GLib prior to 1.2.3, this function may return -1 if the output -was truncated, and the truncated string may not be NULL-terminated. +was truncated, and the truncated string may not be nul-terminated. @@ -191,7 +191,7 @@ documentation. A safer form of the standard vsprintf() function. The output is guaranteed to not exceed @n characters (including the -terminating NULL character), so it is easy to ensure that a buffer overflow +terminating nul character), so it is easy to ensure that a buffer overflow cannot occur. @@ -200,7 +200,7 @@ See also g_strdup_vprintf(). In versions of GLib prior to 1.2.3, this function may return -1 if the output -was truncated, and the truncated string may not be NULL-terminated. +was truncated, and the truncated string may not be nul-terminated. @@ -612,7 +612,7 @@ to the @new_delimiter character. @string: the string to convert. -@delimiters: a string containing the current delimiters, or NULL to use the +@delimiters: a string containing the current delimiters, or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS. @new_delimiter: the new delimiter character. @Returns: @@ -641,7 +641,7 @@ g_strcompress() does the reverse conversion. @source: a string to escape. @exceptions: a string of characters not to escape in @source. -@Returns: a newly allocated copy of @source with certain +@Returns: a newly-allocated copy of @source with certain characters escaped. See above. @@ -652,7 +652,7 @@ does the reverse conversion of g_strescape(). @source: a string to compress. -@Returns: a newly allocated copy of @source with all escaped +@Returns: a newly-allocated copy of @source with all escaped character compressed. @@ -661,13 +661,13 @@ character compressed. For each character in @string, if the character is not in @valid_chars, replaces the character with @substitutor. Modifies @string in place, and return @string itself, not a copy. The return value is to allow -nesting such as g_strup (g_strcanon (str)). +nesting such as g_strup (g_strcanon (str)). -@string: a nul-terminated array of bytes -@valid_chars: bytes permitted in @string -@substitutor: replacement character for disallowed bytes -@Returns: @string +@string: a nul-terminated array of bytes. +@valid_chars: bytes permitted in @string. +@substitutor: replacement character for disallowed bytes. +@Returns: @string. @@ -682,10 +682,10 @@ nesting such as g_strup (g_strcanon (str)). -Frees a NULL-terminated array of strings, and the array itself. +Frees a %NULL-terminated array of strings, and the array itself. -@str_array: a NULL-terminated array of strings to free. +@str_array: a %NULL-terminated array of strings to free. @@ -696,8 +696,8 @@ END WITH %NULL. If you forget the %NULL, g_strconcat() will start appending random memory junk to your string. -@string1: The first string to add, which must not be NULL. -@Varargs: a NULL-terminated list of strings to append to the string. +@string1: The first string to add, which must not be %NULL. +@Varargs: a %NULL-terminated list of strings to append to the string. @Returns: a newly-allocated string containing all the string arguments. @@ -707,8 +707,8 @@ Joins a number of strings together to form one long string, with the optional @separator inserted between each of them. -@separator: a string to insert between each of the strings, or NULL. -@Varargs: a NULL-terminated list of strings to join. +@separator: a string to insert between each of the strings, or %NULL. +@Varargs: a %NULL-terminated list of strings to join. @Returns: a newly-allocated string containing all of the strings joined together, with @separator between them. @@ -719,8 +719,8 @@ Joins a number of strings together to form one long string, with the optional @separator inserted between each of them. -@separator: a string to insert between each of the strings, or NULL. -@str_array: a NULL-terminated array of strings to join. +@separator: a string to insert between each of the strings, or %NULL. +@str_array: a %NULL-terminated array of strings to join. @Returns: a newly-allocated string containing all of the strings joined together, with @separator between them. diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml index 1b9d614..1029c7e 100644 --- a/docs/reference/glib/tmpl/threads.sgml +++ b/docs/reference/glib/tmpl/threads.sgml @@ -145,13 +145,13 @@ This struct should only be used, if you know, what you are doing. Before you use a thread related function in GLib, you should initialize the thread system. This is done by calling g_thread_init(). Most of the time you will only have to call -g_thread_init(NULL). +g_thread_init(NULL). -You should only call g_thread_init() with a non-NULL parameter, if you -really know, what you are doing. +You should only call g_thread_init() with a non-%NULL parameter if you +really know what you are doing. @@ -184,8 +184,8 @@ will abort, if no thread system is available in GLib, i.e. either -If no thread system is available and @vtable is NULL or if not all -elements of @vtable are non-NULL, then g_thread_init() will abort. +If no thread system is available and @vtable is %NULL or if not all +elements of @vtable are non-%NULL, then g_thread_init() will abort. @@ -199,7 +199,7 @@ libraries. @vtable: a function table of type #GThreadFunctions, that provides the -entry points to the thread system to be used +entry points to the thread system to be used. @@ -215,7 +215,7 @@ you can however use it as if it was a function. -@Returns: TRUE, if the thread system is initialized +@Returns: %TRUE, if the thread system is initialized. @@ -224,9 +224,9 @@ Specifies the type of the @func functions passed to g_thread_create() or g_thread_create_full(). -@data: data passed to the thread +@data: data passed to the thread. @Returns: the return value of the thread, which will be returned by -g_thread_join() +g_thread_join(). @@ -274,7 +274,7 @@ This function creates a new thread with the priority @priority. -If @joinable is #TRUE, you can wait for this threads termination +If @joinable is %TRUE, you can wait for this threads termination calling g_thread_wait(). Otherwise the thread will just disappear, when ready. @@ -285,15 +285,15 @@ The new thread executes the function @func with the argument -@error can be NULL to ignore errors, or non-NULL to report errors. The -error is set, if and only if the function returns #NULL. +@error can be %NULL to ignore errors, or non-%NULL to report errors. The +error is set, if and only if the function returns %NULL. -@func: a function to execute in the new thread -@data: an argument to supply to the new thread +@func: a function to execute in the new thread. +@data: an argument to supply to the new thread. @joinable: should this thread be joinable? @error: return location for error. -@Returns: the new #GThread on success +@Returns: the new #GThread on success. @@ -304,9 +304,9 @@ platform, if @stack_size is 0. -If @joinable is #TRUE, you can wait for this threads termination +If @joinable is %TRUE, you can wait for this threads termination calling g_thread_wait(). Otherwise the thread will just disappear, when -ready. If @bound is #TRUE, this thread will be scheduled in the system +ready. If @bound is %TRUE, this thread will be scheduled in the system scope, otherwise the implementation is free to do scheduling in the process scope. The first variant is more expensive resource-wise, but generally faster. On some systems (e.g. Linux) all threads are bound. @@ -318,8 +318,8 @@ The new thread executes the function @func with the argument -@error can be NULL to ignore errors, or non-NULL to report errors. The -error is set, if and only if the function returns #NULL. +@error can be %NULL to ignore errors, or non-%NULL to report errors. The +error is set, if and only if the function returns %NULL. @@ -342,14 +342,14 @@ used for cases, where it is inevitable. -@func: a function to execute in the new thread -@data: an argument to supply to the new thread -@stack_size: a stack size for the new thread +@func: a function to execute in the new thread. +@data: an argument to supply to the new thread. +@stack_size: a stack size for the new thread. @joinable: should this thread be joinable? @bound: should this thread be bound to a system thread? -@priority: a priority for the thread +@priority: a priority for the thread. @error: return location for error. -@Returns: the new #GThread on success +@Returns: the new #GThread on success. @@ -357,7 +357,7 @@ used for cases, where it is inevitable. This functions returns the #GThread corresponding to the calling thread. -@Returns: the current thread +@Returns: the current thread. @@ -365,13 +365,13 @@ This functions returns the #GThread corresponding to the calling thread. Waits until @thread finishes, i.e. the function @func, as given to g_thread_create, returns or g_thread_exit() is called by @thread. All resources of @thread including the #GThread struct are -released. @thread must have been created with @joinable=#TRUE in +released. @thread must have been created with @joinable=%TRUE in g_thread_create(). The value returned by @func or given to g_thread_exit() by @thread is returned by this function. -@thread: a #GThread to be waited for -@Returns: the return value of the thread +@thread: a #GThread to be waited for. +@Returns: the return value of the thread. @@ -389,8 +389,8 @@ being dependent on priorities. -@thread: a #GThread -@priority: a new priority for @thread +@thread: a #GThread. +@priority: a new priority for @thread. @@ -447,7 +447,7 @@ results. -@retval: the return value of this thread +@retval: the return value of this thread. @@ -550,8 +550,9 @@ A #GMutex should only be accessed via the following functions. -All of the g_mutex_* functions are actually macros. Apart from taking -the addresses of them, you can however use them as if they were functions. +All of the g_mutex_* functions are actually macros. +Apart from taking their addresses, you can however use them as if they +were functions. @@ -568,7 +569,7 @@ This function will abort, if g_thread_init() has not been called yet. -@Returns: a new #GMutex +@Returns: a new #GMutex. @@ -592,32 +593,32 @@ has locked @mutex while calling g_mutex_lock(). Use -@mutex: a #GMutex +@mutex: a #GMutex. Tries to lock @mutex. If @mutex is already locked by another -thread, it immediately returns FALSE. Otherwise it locks @mutex -and returns TRUE. +thread, it immediately returns %FALSE. Otherwise it locks @mutex +and returns %TRUE. This function can also be used, if g_thread_init() has not yet been -called and will immediately return TRUE then. +called and will immediately return %TRUE then. -#GMutex is not recursive, i.e. g_mutex_trylock() will return FALSE, +#GMutex is not recursive, i.e. g_mutex_trylock() will return %FALSE, if the current thread already has locked @mutex. Use #GStaticRecMutex instead, if you need recursive mutexes. -@mutex: a #GMutex -@Returns: TRUE, if @mutex could be locked +@mutex: a #GMutex. +@Returns: %TRUE, if @mutex could be locked. @@ -632,7 +633,7 @@ This function can also be used, if g_thread_init() has not yet been called and will do nothing then. -@mutex: a #GMutex +@mutex: a #GMutex. @@ -641,7 +642,7 @@ called and will do nothing then. Destroys @mutex. -@mutex: a #GMutex +@mutex: a #GMutex. @@ -680,7 +681,7 @@ use g_mutex_new() and thus #GMutex, as that requires a prior call to g_thread_init(). In theses cases you can also use a #GStaticMutex. It must be initialized with g_static_mutex_init() before using it and freed with with g_static_mutex_free() when not needed anymore to free -up any allocated recourses. +up any allocated resources. @@ -690,15 +691,15 @@ platforms. -All of the g_static_mutex_* functions can also be used, if -g_thread_init() has not yet been called. +All of the g_static_mutex_* functions can also be +used, if g_thread_init() has not yet been called. -All of the g_static_mutex_* functions are actually macros. Apart from -taking the addresses of them, you can however use them as if they were -functions. +All of the g_static_mutex_* functions are actually +macros. Apart from taking their addresses, you can however use them +as if they were functions. @@ -728,7 +729,7 @@ Initializes @mutex. Alternatively you can initialize it with #G_STATIC_MUTEX_INIT. -@mutex: a #GStaticMutex to be initialized +@mutex: a #GStaticMutex to be initialized. @@ -736,7 +737,7 @@ Initializes @mutex. Alternatively you can initialize it with Works like g_mutex_lock(), but for a #GStaticMutex. -@mutex: a #GStaticMutex +@mutex: a #GStaticMutex. @@ -745,8 +746,8 @@ Works like g_mutex_lock(), but for a #GStaticMutex. Works like g_mutex_trylock(), but for a #GStaticMutex. -@mutex: a #GStaticMutex -@Returns: TRUE, if the #GStaticMutex could be locked +@mutex: a #GStaticMutex. +@Returns: %TRUE, if the #GStaticMutex could be locked. @@ -755,7 +756,7 @@ Works like g_mutex_trylock(), but for a #GStaticMutex. Works like g_mutex_unlock(), but for a #GStaticMutex. -@mutex: a #GStaticMutex +@mutex: a #GStaticMutex. @@ -766,8 +767,8 @@ instead of a #GStaticMutex. This function will return the corresponding #GMutex for @mutex. -@mutex: a #GStaticMutex -@Returns: the #GMutex corresponding to @mutex +@mutex: a #GStaticMutex. +@Returns: the #GMutex corresponding to @mutex. @@ -782,13 +783,13 @@ unbounded lifetime, i.e. objects declared 'static', but if you have a you should also free the #GStaticMutex. -@mutex: a #GStaticMutex to be freed +@mutex: a #GStaticMutex to be freed. -The G_LOCK_* macros provide a convenient interface to #GStaticMutex +The %G_LOCK_* macros provide a convenient interface to #GStaticMutex with the advantage that they will expand to nothing in programs compiled against a thread-disabled GLib, saving code and memory there. #G_LOCK_DEFINE defines a lock. It can appear, where variable @@ -797,7 +798,7 @@ function or outside of functions. The @name parameter will be mangled to get the name of the #GStaticMutex. This means, that you can use names of existing variables as the parameter, e.g. the name of the variable you intent 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: @@ -820,7 +821,7 @@ int give_me_next_number () -@name: the name of the lock +@name: the name of the lock. @@ -829,7 +830,7 @@ int give_me_next_number () This works like #G_LOCK_DEFINE, but it creates a static object. -@name: the name of the lock +@name: the name of the lock. @@ -838,7 +839,7 @@ This works like #G_LOCK_DEFINE, but it creates a static object. This declares a lock, that is defined with #G_LOCK_DEFINE in another module. -@name: the name of the lock +@name: the name of the lock. @@ -847,7 +848,7 @@ This declares a lock, that is defined with #G_LOCK_DEFINE in another module. Works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE. -@name: the name of the lock +@name: the name of the lock. @@ -856,8 +857,8 @@ Works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE. Works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE. -@name: the name of the lock -@Returns: TRUE, if the lock could be locked +@name: the name of the lock. +@Returns: %TRUE, if the lock could be locked. @@ -866,7 +867,7 @@ Works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE. Works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE. -@name: the name of the lock +@name: the name of the lock. @@ -886,8 +887,8 @@ the following functions. -All of the g_static_rec_mutex_* functions can also be used, if -g_thread_init() has not been called. +All of the g_static_rec_mutex_* functions can also +be used, if g_thread_init() has not been called. @mutex: @@ -919,7 +920,7 @@ can be used. Alternatively you can initialize it with #G_STATIC_REC_MUTEX_INIT. -@mutex: a #GStaticRecMutex to be initialized +@mutex: a #GStaticRecMutex to be initialized. @@ -930,19 +931,19 @@ thread. If @mutex is already locked by the calling thread, this functions increases the depth of @mutex and returns immediately. -@mutex: a #GStaticRecMutex to lock +@mutex: a #GStaticRecMutex to lock. Tries to lock @mutex. If @mutex is already locked by another thread, -it immediately returns #FALSE. Otherwise it locks @mutex and returns -#TRUE. If @mutex is already locked by the calling thread, this -functions increases the depth of @mutex and immediately returns #TRUE. +it immediately returns %FALSE. Otherwise it locks @mutex and returns +%TRUE. If @mutex is already locked by the calling thread, this +functions increases the depth of @mutex and immediately returns %TRUE. -@mutex: a #GStaticRecMutex to lock -@Returns: TRUE, if @mutex could be locked +@mutex: a #GStaticRecMutex to lock. +@Returns: %TRUE, if @mutex could be locked. @@ -954,16 +955,16 @@ g_static_rec_mutex_lock() call for @mutex, it will be woken and can lock @mutex itself. -@mutex: a #GStaticRecMutex to unlock +@mutex: a #GStaticRecMutex to unlock. -Works like calling g_static_rec_mutex_lock() for @mutex n times. +Works like calling g_static_rec_mutex_lock() for @mutex @depth times. -@mutex: a #GStaticRecMutex to lock -@depth: number of times this mutex has to be unlocked to be completely unlocked +@mutex: a #GStaticRecMutex to lock. +@depth: number of times this mutex has to be unlocked to be completely unlocked. @@ -977,8 +978,8 @@ g_static_rec_mutex_lock_full() with the depth returned by this function. -@mutex: a #GStaticRecMutex to completely unlock -@Returns: number of times @mutex has been locked by the current thread +@mutex: a #GStaticRecMutex to completely unlock. +@Returns: number of times @mutex has been locked by the current thread. @@ -993,7 +994,7 @@ unbounded lifetime, i.e. objects declared 'static', but if you have a freed, you should also free the #GStaticRecMutex. -@mutex: a #GStaticRecMutex to be freed +@mutex: a #GStaticRecMutex to be freed. @@ -1049,11 +1050,11 @@ example: This example shows an array, which can be accessed by many readers -(the my_array_get function) simultaneously, whereas the writers (the -my_array_set function) only will be allowed once a time and only if no -readers currently access the array. This is because of the potentially -dangerous resizing of the array. Using that functions is fully -multi-thread safe now. +(the my_array_get() function) simultaneously, +whereas the writers (the my_array_set() function) +will only be allowed once a time and only if no readers currently access +the array. This is because of the potentially dangerous resizing of the +array. Using these functions is fully multi-thread safe now. @@ -1071,8 +1072,8 @@ the following functions. -All of the g_static_rw_lock_* functions can also be used, if -g_thread_init() has not been called. +All of the g_static_rw_lock_* functions can also be +used, if g_thread_init() has not been called. @@ -1121,7 +1122,7 @@ be used. Alternatively you can initialize it with #G_STATIC_RW_LOCK_INIT. -@lock: a #GStaticRWLock to be initialized +@lock: a #GStaticRWLock to be initialized. @@ -1141,20 +1142,20 @@ recursivly lock for reading, but that can result in a deadlock as well, due to writer preference. -@lock: a #GStaticRWLock to lock for reading +@lock: a #GStaticRWLock to lock for reading. Tries to lock @lock for reading. If @lock is already locked for writing by another thread or if another thread is already waiting to -lock @lock for writing, it immediately returns #FALSE. Otherwise it -locks @lock for reading and returns TRUE. This lock has to be unlocked +lock @lock for writing, it immediately returns %FALSE. Otherwise it +locks @lock for reading and returns %TRUE. This lock has to be unlocked by g_static_rw_lock_reader_unlock(). -@lock: a #GStaticRWLock to lock for reading -@Returns: TRUE, if @lock could be locked for reading +@lock: a #GStaticRWLock to lock for reading. +@Returns: %TRUE, if @lock could be locked for reading. @@ -1164,7 +1165,7 @@ locks for reading have been unlocked, the waiting thread is woken up and can lock @lock for writing. -@lock: a #GStaticRWLock to unlock after reading +@lock: a #GStaticRWLock to unlock after reading. @@ -1178,19 +1179,19 @@ reading. When @lock is locked for writing, no other thread can lock by g_static_rw_lock_writer_unlock(). -@lock: a #GStaticRWLock to lock for writing +@lock: a #GStaticRWLock to lock for writing. Tries to lock @lock for writing. If @lock is already locked (for either reading or writing) by another thread, it immediately returns -#FALSE. Otherwise it locks @lock for writing and returns TRUE. This +%FALSE. Otherwise it locks @lock for writing and returns %TRUE. This lock has to be unlocked by g_static_rw_lock_writer_unlock(). -@lock: a #GStaticRWLock to lock for writing -@Returns: TRUE, if @lock could be locked for writing +@lock: a #GStaticRWLock to lock for writing. +@Returns: %TRUE, if @lock could be locked for writing. @@ -1202,7 +1203,7 @@ writing and threads wait to lock @lock for reading, the waiting threads are woken up and can lock @lock for reading. -@lock: a #GStaticRWLock to unlock after writing +@lock: a #GStaticRWLock to unlock after writing. @@ -1217,7 +1218,7 @@ unbounded lifetime, i.e. objects declared 'static', but if you have a you should also free the #GStaticRWLock. -@lock: a #GStaticRWLock to be freed +@lock: a #GStaticRWLock to be freed. @@ -1263,9 +1264,9 @@ gpointer pop_data () -Whenever a thread calls pop_data() now, it will wait until -current_data is non-NULL, i.e. until some other thread has called -push_data(). +Whenever a thread calls pop_data() now, it will +wait until current_data is non-%NULL, i.e. until some other thread +has called push_data(). @@ -1286,8 +1287,9 @@ A #GCond should only be accessed via the following functions. -All of the g_cond_* functions are actually macros. Apart from taking -the addresses of them, you can however use them as if they were functions. +All of the g_cond_* functions are actually macros. +Apart from taking their addresses, you can however use them as if they +were functions. @@ -1299,7 +1301,7 @@ Creates a new #GCond. This function will abort, if g_thread_init() has not been called yet. -@Returns: a new #GCond +@Returns: a new #GCond. @@ -1314,7 +1316,7 @@ This function can also be used, if g_thread_init() has not yet been called and will do nothing then. -@cond: a #GCond +@cond: a #GCond. @@ -1330,7 +1332,7 @@ This function can also be used, if g_thread_init() has not yet been called and will do nothing then. -@cond: a #GCond +@cond: a #GCond. @@ -1345,8 +1347,8 @@ This function can also be used, if g_thread_init() has not yet been called and will immediately return then. -@cond: a #GCond -@mutex: a #GMutex, that is currently locked +@cond: a #GCond. +@mutex: a #GMutex, that is currently locked. @@ -1358,12 +1360,12 @@ unlocked before falling asleep and locked again before resuming. -If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait(). +If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait(). This function can also be used, if g_thread_init() has not yet been -called and will immediately return TRUE then. +called and will immediately return %TRUE then. @@ -1371,10 +1373,10 @@ To easily calculate @abs_time a combination of g_get_current_time() and g_time_val_add() can be used. -@cond: a #GCond -@mutex: a #GMutex, that is currently locked -@abs_time: a #GTimeVal, determining the final time -@Returns: TRUE, if the thread is woken up in time +@cond: a #GCond. +@mutex: a #GMutex, that is currently locked. +@abs_time: a #GTimeVal, determining the final time. +@Returns: %TRUE, if the thread is woken up in time. @@ -1383,15 +1385,16 @@ and g_time_val_add() can be used. Destroys the #GCond. -@cond: a #GCond +@cond: a #GCond. The #GPrivate struct is an opaque data structure to represent a thread private data key. Threads can thereby obtain and set a pointer, which -is private to the current thread. Take our give_me_next_number() -example from above. Now we don't want current_number to be shared +is private to the current thread. +Take our give_me_next_number() example from above. +Now we don't want current_number to be shared between the threads, but to be private to each thread. This can be done as follows: @@ -1419,11 +1422,10 @@ done as follows: -Here the pointer belonging to the key current_number_key is read. If -it is NULL, it has not been set yet. Then get memory for an integer -value, assign this memory to the pointer and write the pointer -back. Now we have an integer value, that is private to the current -thread. +Here the pointer belonging to the key current_number_key +is read. If it is %NULL, it has not been set yet. Then get memory for an +integer value, assign this memory to the pointer and write the pointer +back. Now we have an integer value, that is private to the current thread. @@ -1432,8 +1434,9 @@ The #GPrivate struct should only be accessed via the following functions. -All of the g_private_* functions are actually macros. Apart from taking -the addresses of them, you can however use them as if they were functions. +All of the g_private_* functions are actually macros. +Apart from taking their addresses, you can however use them as if they were +functions. @@ -1441,9 +1444,9 @@ the addresses of them, you can however use them as if they were functions. -Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer +Creates a new #GPrivate. If @destructor is non-%NULL, it is a pointer to a destructor function. Whenever a thread ends and the corresponding -pointer keyed to this instance of #GPrivate is non-NULL, the +pointer keyed to this instance of #GPrivate is non-%NULL, the destructor is called with this pointer as the argument. @@ -1468,15 +1471,15 @@ This function will abort, if g_thread_init() has not been called yet. @destructor: a function to handle the data keyed to #GPrivate, when a -thread ends -@Returns: a new #GPrivate +thread ends. +@Returns: a new #GPrivate. Returns the pointer keyed to @private_key for the current thread. This -pointer is NULL, when g_private_set() hasn't been called for the +pointer is %NULL, when g_private_set() hasn't been called for the current @private_key and thread yet. @@ -1485,8 +1488,8 @@ This function can also be used, if g_thread_init() has not yet been called and will return the value of @private_key casted to #gpointer then. -@private_key: a #GPrivate -@Returns: the corresponding pointer +@private_key: a #GPrivate. +@Returns: the corresponding pointer. @@ -1500,8 +1503,8 @@ This function can also be used, if g_thread_init() has not yet been called and will set @private_key to @data casted to #GPrivate* then. -@private_key: a #GPrivate -@data: the new pointer +@private_key: a #GPrivate. +@data: the new pointer. @@ -1511,7 +1514,7 @@ A #GStaticPrivate works almost like a #GPrivate, but it has one significant advantage. It doesn't need to be created at run-time like a #GPrivate, but can be defined at compile-time. This is similar to the difference between #GMutex and #GStaticMutex. Now look at our -give_me_next_number() example with #GStaticPrivate: +give_me_next_number() example with #GStaticPrivate: @@ -1560,7 +1563,7 @@ Initializes @private_key. Alternatively you can initialize it with #G_STATIC_PRIVATE_INIT. -@private_key: a #GStaticPrivate to be initialized +@private_key: a #GStaticPrivate to be initialized. @@ -1572,14 +1575,14 @@ Works like g_private_get() only for a #GStaticPrivate. This function also works, if g_thread_init() has not yet been called. -@private_key: a #GStaticPrivate -@Returns: the corresponding pointer +@private_key: a #GStaticPrivate. +@Returns: the corresponding pointer. Sets the pointer keyed to @private_key for the current thread and the -function @notify to be called with that pointer (NULL or non-NULL), +function @notify to be called with that pointer (%NULL or non-%NULL), whenever the pointer is set again or whenever the current thread ends. @@ -1597,10 +1600,10 @@ g_private_new(). -@private_key: a #GStaticPrivate -@data: the new pointer +@private_key: a #GStaticPrivate. +@data: the new pointer. @notify: a function to be called with the pointer, whenever the -current thread ends or sets this pointer again +current thread ends or sets this pointer again. @@ -1615,6 +1618,5 @@ unbounded lifetime, i.e. objects declared 'static', but if you have a you should also free the #GStaticPrivate. -@private_key: a #GStaticPrivate to be freed - +@private_key: a #GStaticPrivate to be freed. diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml index afa41e8..dabd521 100644 --- a/docs/reference/glib/tmpl/trees-nary.sgml +++ b/docs/reference/glib/tmpl/trees-nary.sgml @@ -58,7 +58,7 @@ The next and prev fields point to the node's siblings (a sibling is another #GNode with the same parent). The parent field points to the parent of the #GNode, -or is NULL if the #GNode is the root of the tree. +or is %NULL if the #GNode is the root of the tree. The children field points to the first child of the #GNode. The other children are accessed by using the next pointer of each child. -- 2.7.4