diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | ChangeLog.pre-2-0 | 6 | ||||
| -rw-r--r-- | ChangeLog.pre-2-10 | 6 | ||||
| -rw-r--r-- | ChangeLog.pre-2-12 | 6 | ||||
| -rw-r--r-- | ChangeLog.pre-2-2 | 6 | ||||
| -rw-r--r-- | ChangeLog.pre-2-4 | 6 | ||||
| -rw-r--r-- | ChangeLog.pre-2-6 | 6 | ||||
| -rw-r--r-- | ChangeLog.pre-2-8 | 6 | ||||
| -rw-r--r-- | docs/reference/ChangeLog | 4 | ||||
| -rw-r--r-- | docs/reference/glib/tmpl/caches.sgml | 2 | ||||
| -rw-r--r-- | glib/gasyncqueue.c | 38 | ||||
| -rw-r--r-- | glib/gerror.c | 26 | ||||
| -rw-r--r-- | glib/gfileutils.c | 83 | ||||
| -rw-r--r-- | glib/ghash.c | 26 | ||||
| -rw-r--r-- | glib/gmain.c | 108 | ||||
| -rw-r--r-- | glib/gshell.c | 4 | ||||
| -rw-r--r-- | glib/gspawn-win32.c | 96 | ||||
| -rw-r--r-- | glib/gspawn.c | 93 | ||||
| -rw-r--r-- | glib/gtree.c | 16 |
19 files changed, 302 insertions, 242 deletions
@@ -1,3 +1,9 @@ +2001-12-15 Matthias Clasen <matthiasc@poet.de> + + * glib/gshell.c, glib/gspawn.c, glib/gspawn-win32.c, glib/gerror.c, + glib/gfileutils.c, glib/ghash.c, glib/gmain.c, glib/gasyncqueue.c, + glib/gtree.c: Minor markup fixes. + 2001-12-14 Havoc Pennington <hp@pobox.com> * glib/gshell.c (g_shell_parse_argv): note on how to free returned diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 80fbeb378..ab77fe008 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,9 @@ +2001-12-15 Matthias Clasen <matthiasc@poet.de> + + * glib/gshell.c, glib/gspawn.c, glib/gspawn-win32.c, glib/gerror.c, + glib/gfileutils.c, glib/ghash.c, glib/gmain.c, glib/gasyncqueue.c, + glib/gtree.c: Minor markup fixes. + 2001-12-14 Havoc Pennington <hp@pobox.com> * glib/gshell.c (g_shell_parse_argv): note on how to free returned diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 80fbeb378..ab77fe008 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,9 @@ +2001-12-15 Matthias Clasen <matthiasc@poet.de> + + * glib/gshell.c, glib/gspawn.c, glib/gspawn-win32.c, glib/gerror.c, + glib/gfileutils.c, glib/ghash.c, glib/gmain.c, glib/gasyncqueue.c, + glib/gtree.c: Minor markup fixes. + 2001-12-14 Havoc Pennington <hp@pobox.com> * glib/gshell.c (g_shell_parse_argv): note on how to free returned diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 80fbeb378..ab77fe008 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,3 +1,9 @@ +2001-12-15 Matthias Clasen <matthiasc@poet.de> + + * glib/gshell.c, glib/gspawn.c, glib/gspawn-win32.c, glib/gerror.c, + glib/gfileutils.c, glib/ghash.c, glib/gmain.c, glib/gasyncqueue.c, + glib/gtree.c: Minor markup fixes. + 2001-12-14 Havoc Pennington <hp@pobox.com> * glib/gshell.c (g_shell_parse_argv): note on how to free returned diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 80fbeb378..ab77fe008 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,9 @@ +2001-12-15 Matthias Clasen <matthiasc@poet.de> + + * glib/gshell.c, glib/gspawn.c, glib/gspawn-win32.c, glib/gerror.c, + glib/gfileutils.c, glib/ghash.c, glib/gmain.c, glib/gasyncqueue.c, + glib/gtree.c: Minor markup fixes. + 2001-12-14 Havoc Pennington <hp@pobox.com> * glib/gshell.c (g_shell_parse_argv): note on how to free returned diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 80fbeb378..ab77fe008 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,9 @@ +2001-12-15 Matthias Clasen <matthiasc@poet.de> + + * glib/gshell.c, glib/gspawn.c, glib/gspawn-win32.c, glib/gerror.c, + glib/gfileutils.c, glib/ghash.c, glib/gmain.c, glib/gasyncqueue.c, + glib/gtree.c: Minor markup fixes. + 2001-12-14 Havoc Pennington <hp@pobox.com> * glib/gshell.c (g_shell_parse_argv): note on how to free returned diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 80fbeb378..ab77fe008 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,9 @@ +2001-12-15 Matthias Clasen <matthiasc@poet.de> + + * glib/gshell.c, glib/gspawn.c, glib/gspawn-win32.c, glib/gerror.c, + glib/gfileutils.c, glib/ghash.c, glib/gmain.c, glib/gasyncqueue.c, + glib/gtree.c: Minor markup fixes. + 2001-12-14 Havoc Pennington <hp@pobox.com> * glib/gshell.c (g_shell_parse_argv): note on how to free returned diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 80fbeb378..ab77fe008 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,9 @@ +2001-12-15 Matthias Clasen <matthiasc@poet.de> + + * glib/gshell.c, glib/gspawn.c, glib/gspawn-win32.c, glib/gerror.c, + glib/gfileutils.c, glib/ghash.c, glib/gmain.c, glib/gasyncqueue.c, + glib/gtree.c: Minor markup fixes. + 2001-12-14 Havoc Pennington <hp@pobox.com> * glib/gshell.c (g_shell_parse_argv): note on how to free returned diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 869fa3a38..021519732 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2001-12-15 Matthias Clasen <matthias@poet.de> + + * glib/tmpl/caches.sgml: GCs are cached by GTK, not by GDK. + 2001-12-14 Matthias Clasen <matthias@poet.de> * glib/tmpl/memory.sgml: Typo fixes. diff --git a/docs/reference/glib/tmpl/caches.sgml b/docs/reference/glib/tmpl/caches.sgml index 99c344b68..71b8b6fc9 100644 --- a/docs/reference/glib/tmpl/caches.sgml +++ b/docs/reference/glib/tmpl/caches.sgml @@ -10,7 +10,7 @@ A #GCache allows sharing of complex data structures, in order to save system resources. </para> <para> -GTK+ uses a #GCache for #GtkStyles; GDK uses one for #GdkGCs. These consume a lot of +GTK+ uses caches for #GtkStyles and #GdkGCs. These consume a lot of resources, so a #GCache is used to see if a #GtkStyle or #GdkGC with the required properties already exists. If it does, then the existing object is used instead of creating a new one. diff --git a/glib/gasyncqueue.c b/glib/gasyncqueue.c index c6624799a..2da05e7a5 100644 --- a/glib/gasyncqueue.c +++ b/glib/gasyncqueue.c @@ -97,8 +97,8 @@ g_async_queue_ref_unlocked (GAsyncQueue *queue) * destroyed and the memory allocated will be freed. So you are not * allowed to use the @queue afterwards, as it might have disappeared. * The obvious asymmetry (it is not named - * g_async_queue_unref_unlocked) is because the queue can't be - * unlocked after dereffing it, as it might already have disappeared. + * g_async_queue_unref_unlocked()) is because the queue can't be + * unlocked after unreffing it, as it might already have disappeared. **/ void g_async_queue_unref_and_unlock (GAsyncQueue *queue) @@ -145,8 +145,8 @@ g_async_queue_unref (GAsyncQueue *queue) * g_async_queue_lock: * @queue: a #GAsyncQueue. * - * Acquire the @queue's lock. After that you can only call the - * g_async_queue_*_unlocked function variants on that + * Acquires the @queue's lock. After that you can only call the + * <function>g_async_queue_*_unlocked()</function> function variants on that * @queue. Otherwise it will deadlock. **/ void @@ -162,7 +162,7 @@ g_async_queue_lock (GAsyncQueue *queue) * g_async_queue_unlock: * @queue: a #GAsyncQueue. * - * Release the queue's lock. + * Releases the queue's lock. **/ void g_async_queue_unlock (GAsyncQueue *queue) @@ -178,7 +178,7 @@ g_async_queue_unlock (GAsyncQueue *queue) * @queue: a #GAsyncQueue. * @data: @data to push into the @queue. * - * Push the @data into the @queue. @data must not be #NULL. + * Pushes the @data into the @queue. @data must not be %NULL. **/ void g_async_queue_push (GAsyncQueue* queue, gpointer data) @@ -197,7 +197,7 @@ g_async_queue_push (GAsyncQueue* queue, gpointer data) * @queue: a #GAsyncQueue. * @data: @data to push into the @queue. * - * Push the @data into the @queue. @data must not be #NULL. This + * Pushes the @data into the @queue. @data must not be %NULL. This * function must be called while holding the @queue's lock. **/ void @@ -251,7 +251,7 @@ g_async_queue_pop_intern_unlocked (GAsyncQueue* queue, gboolean try, * g_async_queue_pop: * @queue: a #GAsyncQueue. * - * Pop data from the @queue. This function blocks until data become + * Pops data from the @queue. This function blocks until data become * available. * * Return value: data from the queue. @@ -275,7 +275,7 @@ g_async_queue_pop (GAsyncQueue* queue) * g_async_queue_pop_unlocked: * @queue: a #GAsyncQueue. * - * Pop data from the @queue. This function blocks until data become + * Pops data from the @queue. This function blocks until data become * available. This function must be called while holding the @queue's * lock. * @@ -294,10 +294,10 @@ g_async_queue_pop_unlocked (GAsyncQueue* queue) * g_async_queue_try_pop: * @queue: a #GAsyncQueue. * - * Try to pop data from the @queue. If no data is available, #NULL is + * Tries to pop data from the @queue. If no data is available, %NULL is * returned. * - * Return value: data from the queue or #NULL, when no data is + * Return value: data from the queue or %NULL, when no data is * available immediately. **/ gpointer @@ -319,11 +319,11 @@ g_async_queue_try_pop (GAsyncQueue* queue) * g_async_queue_try_pop_unlocked: * @queue: a #GAsyncQueue. * - * Try to pop data from the @queue. If no data is available, #NULL is + * Tries to pop data from the @queue. If no data is available, %NULL is * returned. This function must be called while holding the @queue's * lock. * - * Return value: data from the queue or #NULL, when no data is + * Return value: data from the queue or %NULL, when no data is * available immediately. **/ gpointer @@ -340,13 +340,13 @@ g_async_queue_try_pop_unlocked (GAsyncQueue* queue) * @queue: a #GAsyncQueue. * @end_time: a #GTimeVal, determining the final time. * - * Pop data from the @queue. If no data is received before @end_time, - * #NULL is returned. + * Pops data from the @queue. If no data is received before @end_time, + * %NULL is returned. * * To easily calculate @end_time a combination of g_get_current_time() * and g_time_val_add() can be used. * - * Return value: data from the queue or #NULL, when no data is + * Return value: data from the queue or %NULL, when no data is * received before @end_time. **/ gpointer @@ -369,14 +369,14 @@ g_async_queue_timed_pop (GAsyncQueue* queue, GTimeVal *end_time) * @queue: a #GAsyncQueue. * @end_time: a #GTimeVal, determining the final time. * - * Pop data from the @queue. If no data is received before @end_time, - * #NULL is returned. This function must be called while holding the + * Pops data from the @queue. If no data is received before @end_time, + * %NULL is returned. This function must be called while holding the * @queue's lock. * * To easily calculate @end_time a combination of g_get_current_time() * and g_time_val_add() can be used. * - * Return value: data from the queue or #NULL, when no data is + * Return value: data from the queue or %NULL, when no data is * received before @end_time. **/ gpointer diff --git a/glib/gerror.c b/glib/gerror.c index eff62588a..664aa2420 100644 --- a/glib/gerror.c +++ b/glib/gerror.c @@ -47,7 +47,7 @@ g_error_new_valist(GQuark domain, * g_error_new: * @domain: error domain * @code: error code - * @format: printf()-style format for error message + * @format: <function>printf()</function>-style format for error message * @Varargs: parameters for message format * * Creates a new #GError with the given @domain and @code, @@ -81,9 +81,9 @@ g_error_new (GQuark domain, * @message: error message * * Creates a new #GError; unlike g_error_new(), @message is not - * a printf()-style format string. Use this function if @message - * contains text you don't have control over, that could include - * printf() escape sequences. + * a <function>printf()</function>-style format string. Use this + * function if @message contains text you don't have control over, + * that could include <function>printf()</function> escape sequences. * * Return value: a new #GError **/ @@ -153,7 +153,7 @@ g_error_copy (const GError *error) * @domain: an error domain * @code: an error code * - * Returns TRUE if @error matches @domain and @code, FALSE + * Returns %TRUE if @error matches @domain and @code, %FALSE * otherwise. * * Return value: whether @error has @domain and @code @@ -174,14 +174,14 @@ g_error_matches (const GError *error, /** * g_set_error: - * @err: a return location for a #GError, or NULL + * @err: a return location for a #GError, or %NULL * @domain: error domain * @code: error code - * @format: printf()-style format + * @format: <function>printf()</function>-style format * @Varargs: args for @format * - * Does nothing if @err is NULL; if @err is non-NULL, then *@err must - * be NULL. A new #GError is created and assigned to *@err. + * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err must + * be %NULL. A new #GError is created and assigned to *@err. **/ void g_set_error (GError **err, @@ -212,8 +212,8 @@ g_set_error (GError **err, * @dest: error return location * @src: error to move into the return location * - * If @dest is NULL, free @src; otherwise, - * moves @src into *@dest. *@dest must be NULL. + * If @dest is %NULL, free @src; otherwise, + * moves @src into *@dest. *@dest must be %NULL. **/ void g_propagate_error (GError **dest, @@ -240,8 +240,8 @@ g_propagate_error (GError **dest, * g_clear_error: * @err: a #GError return location * - * If @err is NULL, does nothing. If @err is non-NULL, - * calls g_error_free() on *@err and sets *@err to NULL. + * If @err is %NULL, does nothing. If @err is non-%NULL, + * calls g_error_free() on *@err and sets *@err to %NULL. **/ void g_clear_error (GError **err) diff --git a/glib/gfileutils.c b/glib/gfileutils.c index 3ab354c4c..1d7a3907f 100644 --- a/glib/gfileutils.c +++ b/glib/gfileutils.c @@ -70,14 +70,14 @@ * @filename: a filename to test * @test: bitfield of #GFileTest flags * - * Returns TRUE if any of the tests in the bitfield @test are - * TRUE. For example, (G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR) - * will return TRUE if the file exists; the check whether it's - * a directory doesn't matter since the existence test is TRUE. - * With the current set of available tests, there's no point + * Returns %TRUE if any of the tests in the bitfield @test are + * %TRUE. For example, <literal>(G_FILE_TEST_EXISTS | + * G_FILE_TEST_IS_DIR)</literal> will return %TRUE if the file exists; + * the check whether it's a directory doesn't matter since the existence + * test is %TRUE. With the current set of available tests, there's no point * passing in more than one test at a time. * - * Return value: whether a test was TRUE + * Return value: whether a test was %TRUE **/ gboolean g_file_test (const gchar *filename, @@ -122,16 +122,16 @@ g_file_error_quark (void) * g_file_error_from_errno: * @err_no: an "errno" value * - * Gets a #GFileError constant based on the passed-in errno. - * For example, if you pass in EEXIST this function returns - * #G_FILE_ERROR_EXIST. Unlike errno values, you can portably + * Gets a #GFileError constant based on the passed-in @errno. + * For example, if you pass in %EEXIST this function returns + * #G_FILE_ERROR_EXIST. Unlike @errno values, you can portably * assume that all #GFileError values will exist. * * Normally a #GFileError value goes into a #GError returned * from a function that manipulates files. So you would use * g_file_error_from_errno() when constructing a #GError. * - * Return value: #GFileError corresponding to the given errno + * Return value: #GFileError corresponding to the given @errno **/ GFileError g_file_error_from_errno (gint err_no) @@ -490,17 +490,17 @@ get_contents_win32 (const gchar *filename, * @error: return location for a #GError * * Reads an entire file into allocated memory, with good error - * checking. If @error is set, FALSE is returned, and @contents is set - * to NULL. If TRUE is returned, @error will not be set, and @contents + * checking. If @error is set, %FALSE is returned, and @contents is set + * to %NULL. If %TRUE is returned, @error will not be set, and @contents * will be set to the file contents. The string stored in @contents - * will be nul-terminated, so for text files you can pass NULL for the + * will be nul-terminated, so for text files you can pass %NULL for the * @length argument. The error domain is #G_FILE_ERROR. Possible * error codes are those in the #GFileError enumeration. * * FIXME currently crashes if the file is too big to fit in memory; * should probably use g_try_malloc() when we have that function. * - * Return value: TRUE on success, FALSE if error is set + * Return value: %TRUE on success, %FALSE if error is set **/ gboolean g_file_get_contents (const gchar *filename, @@ -530,18 +530,19 @@ g_file_get_contents (const gchar *filename, * g_mkstemp: * @tmpl: template filename * - * Open a temporary file. See "man mkstemp" on most UNIX-like systems. - * This is a portability wrapper, which simply calls mkstemp() on systems - * that have it, and implements it in GLib otherwise. + * Opens a temporary file. See the <function>mkstemp()</function> documentation + * on most UNIX-like systems. This is a portability wrapper, which simply calls + * <function>mkstemp()</function> on systems that have it, and implements + * it in GLib otherwise. * - * The parameter is a string that should match the rules for mktemp, i.e. - * end in "XXXXXX". The X string will be modified to form the name - * of a file that didn't exist. + * The parameter is a string that should match the rules for + * <function>mkstemp()</function>, i.e. end in "XXXXXX". The X string will + * be modified to form the name of a file that didn't exist. * - * Return value: A file handle (as from open()) to the file + * Return value: A file handle (as from <function>open()</function>) to the file * opened for reading and writing. The file is opened in binary mode * on platforms where there is a difference. The file handle should be - * closed with close(). In case of errors, -1 is returned. + * closed with <function>close()</function>. In case of errors, -1 is returned. */ int g_mkstemp (char *tmpl) @@ -605,7 +606,7 @@ g_mkstemp (char *tmpl) /** * g_file_open_tmp: - * @tmpl: Template for file name, as in g_mkstemp, basename only + * @tmpl: Template for file name, as in g_mkstemp(), basename only * @name_used: location to store actual name used * @error: return location for a #GError * @@ -613,22 +614,22 @@ g_mkstemp (char *tmpl) * files (as returned by g_get_tmp_dir()). * * @tmpl should be a string ending with six 'X' characters, as the - * parameter to g_mkstemp() (or mkstemp()). However, unlike these - * functions, the template should only be a basename, no directory - * components are allowed. If template is NULL, a default template is - * used. + * parameter to g_mkstemp() (or <function>mkstemp()</function>). + * However, unlike these functions, the template should only be a + * basename, no directory components are allowed. If template is %NULL, + * a default template is used. * - * Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not - * modified, and might thus be a read-only literal string. + * Note that in contrast to g_mkstemp() (and <function>mkstemp()</function>) + * @tmpl is not modified, and might thus be a read-only literal string. * - * The actual name used is returned in @name_used if non-NULL. This - * string should be freed with g_free when not needed any longer. + * The actual name used is returned in @name_used if non-%NULL. This + * string should be freed with g_free() when not needed any longer. * - * Return value: A file handle (as from open()) to the file - * opened for reading and writing. The file is opened in binary mode - * on platforms where there is a difference. The file handle should be - * closed with close(). In case of errors, -1 is returned and - * @error will be set. + * Return value: A file handle (as from <function>open()</function>) to + * the file opened for reading and writing. The file is opened in binary + * mode on platforms where there is a difference. The file handle should be + * closed with <function>close()</function>. In case of errors, -1 is returned + * and @error will be set. **/ int g_file_open_tmp (const char *tmpl, @@ -765,13 +766,13 @@ g_build_pathv (const gchar *separator, * @first_element: the first element in the path * @Varargs: remaining elements in path * - * Create a path from a series of elements using @separator as the + * Creates a path from a series of elements using @separator as the * separator between elements. At the boundary between two elements, * any trailing occurrences of separator in the first element, or * leading occurrences of separator in the second element are removed * and exactly one copy of the separator is inserted. * - * Return value: a newly allocated string that must be freed with g_free(). + * Return value: a newly-allocated string that must be freed with g_free(). **/ gchar * g_build_path (const gchar *separator, @@ -795,15 +796,15 @@ g_build_path (const gchar *separator, * @first_element: the first element in the path * @Varargs: remaining elements in path * - * Create a filename from a series of elements using the correct + * Creates a filename from a series of elements using the correct * separator for filenames. This function behaves identically - * to g_build_path (G_DIR_SEPARATOR_S, first_element, ....) + * to <literal>g_build_path (G_DIR_SEPARATOR_S, first_element, ....)</literal>. * * No attempt is made to force the resulting filename to be an absolute * path. If the first element is a relative path, the result will * be a relative path. * - * Return value: a newly allocated string that must be freed with g_free(). + * Return value: a newly-allocated string that must be freed with g_free(). **/ gchar * g_build_filename (const gchar *first_element, diff --git a/glib/ghash.c b/glib/ghash.c index bd1b63409..a91bcab42 100644 --- a/glib/ghash.c +++ b/glib/ghash.c @@ -96,11 +96,11 @@ static GHashNode *node_free_list = NULL; * Hash values are used to determine where keys are stored within the * #GHashTable data structure. The g_direct_hash(), g_int_hash() and * g_str_hash() functions are provided for some common types of keys. - * If hash_func is NULL, g_direct_hash() is used. + * If hash_func is %NULL, g_direct_hash() is used. * @key_equal_func: a function to check two keys for equality. This is * used when looking up keys in the #GHashTable. The g_direct_equal(), * g_int_equal() and g_str_equal() functions are provided for the most - * common types of keys. If @key_equal_func is NULL, keys are compared + * common types of keys. If @key_equal_func is %NULL, keys are compared * directly in a similar fashion to g_direct_equal(), but without the * overhead of a function call. * @@ -121,10 +121,10 @@ g_hash_table_new (GHashFunc hash_func, * @hash_func: a function to create a hash value from a key. * @key_equal_func: a function to check two keys for equality. * @key_destroy_func: a function to free the memory allocated for the key - * used when removing the entry from the #GHashTable or #NULL if you + * used when removing the entry from the #GHashTable or %NULL if you * don't want to supply such a function. * @value_destroy_func: a function to free the memory allocated for the - * value used when removing the entry from the #GHashTable or #NULL if + * value used when removing the entry from the #GHashTable or %NULL if * you don't want to supply such a function. * * Creates a new #GHashTable like g_hash_table_new() and allows to specify @@ -214,7 +214,7 @@ g_hash_table_lookup_node (GHashTable *hash_table, * * Looks up a key in a #GHashTable. * - * Return value: the associated value, or NULL if the key is not found. + * Return value: the associated value, or %NULL if the key is not found. **/ gpointer g_hash_table_lookup (GHashTable *hash_table, @@ -237,7 +237,7 @@ g_hash_table_lookup (GHashTable *hash_table, * @value: returns the value associated with the key. * * Looks up a key in the #GHashTable, returning the original key and the - * associated value and a gboolean which is TRUE if the key was found. This + * associated value and a #gboolean which is %TRUE if the key was found. This * is useful if you need to free the memory allocated for the original key, * for example before calling g_hash_table_remove(). * @@ -276,9 +276,9 @@ g_hash_table_lookup_extended (GHashTable *hash_table, * Inserts a new key and value into a #GHashTable. * * If the key already exists in the #GHashTable its current value is replaced - * with the new value. If you supplied a value_destroy_func when creating the + * with the new value. If you supplied a @value_destroy_func when creating the * #GHashTable, the old value is freed using that function. If you supplied - * a key_destroy_func when creating the #GHashTable, the passed key is freed + * a @key_destroy_func when creating the #GHashTable, the passed key is freed * using that function. **/ void @@ -325,8 +325,8 @@ g_hash_table_insert (GHashTable *hash_table, * Inserts a new key and value into a #GHashTable similar to * g_hash_table_insert(). The difference is that if the key already exists * in the #GHashTable, it gets replaced by the new key. If you supplied a - * value_destroy_func when creating the #GHashTable, the old value is freed - * using that function. If you supplied a key_destroy_func when creating the + * @value_destroy_func when creating the #GHashTable, the old value is freed + * using that function. If you supplied a @key_destroy_func when creating the * #GHashTable, the old key is freed using that function. **/ void @@ -367,7 +367,7 @@ g_hash_table_replace (GHashTable *hash_table, * Removes a key and its associated value from a #GHashTable. * * If the #GHashTable was created using g_hash_table_new_full(), the - * key and value are freed using the supplied destroy_functions, otherwise + * key and value are freed using the supplied destroy functions, otherwise * you have to make sure that any dynamically allocated values are freed * yourself. * @@ -440,7 +440,7 @@ g_hash_table_steal (GHashTable *hash_table, * @user_data: user data to pass to the function. * * Calls the given function for each key/value pair in the #GHashTable. - * If the function returns TRUE, then the key/value pair is removed from the + * If the function returns %TRUE, then the key/value pair is removed from the * #GHashTable. If you supplied key or value destroy functions when creating * the #GHashTable, they are used to free the memory allocated for the removed * keys and values. @@ -465,7 +465,7 @@ g_hash_table_foreach_remove (GHashTable *hash_table, * @user_data: user data to pass to the function. * * Calls the given function for each key/value pair in the #GHashTable. - * If the function returns TRUE, then the key/value pair is removed from the + * If the function returns %TRUE, then the key/value pair is removed from the * #GHashTable, but no key or value destroy functions are called. * * Return value: the number of key/value pairs removed. diff --git a/glib/gmain.c b/glib/gmain.c index 827ce097a..cc1b02a43 100644 --- a/glib/gmain.c +++ b/glib/gmain.c @@ -660,7 +660,7 @@ g_main_context_new () /** * g_main_context_default: * - * Return the default main context. This is the main context used + * Returns the default main context. This is the main context used * for main loop functions when a main loop is not explicitly * specified. * @@ -687,18 +687,18 @@ g_main_context_default (void) * g_source_new: * @source_funcs: structure containing functions that implement * the sources behavior. - * @struct_size: size of the #GSource structure to create + * @struct_size: size of the #GSource structure to create. * - * Create a new GSource structure. The size is specified to - * allow creating structures derived from GSource that contain + * Creates a new #GSource structure. The size is specified to + * allow creating structures derived from #GSource that contain * additional data. The size passed in must be at least - * sizeof(GSource). + * <literal>sizeof (GSource)</literal>. * * The source will not initially be associated with any #GMainContext * and must be added to one with g_source_add() before it will be * executed. * - * Return value: the newly create #GSource + * Return value: the newly-created #GSource. **/ GSource * g_source_new (GSourceFuncs *source_funcs, @@ -863,7 +863,7 @@ g_source_destroy_internal (GSource *source, * g_source_destroy: * @source: a #GSource * - * Remove a source from its #GMainContext, if any, and mark it as + * Removes a source from its #GMainContext, if any, and mark it as * destroyed. The source cannot be subsequently added to another * context. **/ @@ -886,7 +886,7 @@ g_source_destroy (GSource *source) * g_source_get_id: * @source: a #GSource * - * Return the numeric ID for a particular source. The ID of a source + * Returns the numeric ID for a particular source. The ID of a source * is unique within a particular main loop context. The reverse * mapping from ID to source is done by g_main_context_find_source_by_id(). * @@ -911,7 +911,7 @@ g_source_get_id (GSource *source) * g_source_get_context: * @source: a #GSource * - * Get the #GMainContext with which the source is associated. + * Gets the #GMainContext with which the source is associated. * Calling this function on a destroyed source is an error. * * Return value: the #GMainContext with which the source is associated, @@ -932,10 +932,10 @@ g_source_get_context (GSource *source) * @fd: a #GPollFD structure holding information about a file * descriptor to watch. * - * Add a file descriptor to the set of file descriptors polled for + * Adds a file descriptor to the set of file descriptors polled for * this source. This is usually combined with g_source_new() to add an * event source. The event source's check function will typically test - * the revents field in the #GPollFD struct and return %TRUE if events need + * the @revents field in the #GPollFD struct and return %TRUE if events need * to be processed. **/ void @@ -965,9 +965,9 @@ g_source_add_poll (GSource *source, /** * g_source_remove_poll: * @source:a #GSource - * @fd: a #GPollFD structure previously passed to g_source_poll. + * @fd: a #GPollFD structure previously passed to g_source_poll(). * - * Remove a file descriptor from the set of file descriptors polled for + * Removes a file descriptor from the set of file descriptors polled for * this source. **/ void @@ -998,10 +998,10 @@ g_source_remove_poll (GSource *source, * g_source_set_callback_indirect: * @source: the source * @callback_data: pointer to callback data "object" - * @callback_funcs: functions for reference counting callback_data + * @callback_funcs: functions for reference counting @callback_data * and getting the callback and data * - * Set the callback function storing the data as a refcounted callback + * Sets the callback function storing the data as a refcounted callback * "object". This is used to implement g_source_set_callback_closure() * and internally. Note that calling g_source_set_callback_indirect() assumes * an initial reference count on @callback_data, and thus @@ -1086,7 +1086,7 @@ static GSourceCallbackFuncs g_source_callback_funcs = { * @data: the data to pass to callback function * @notify: a function to call when @data is no longer in use, or %NULL. * - * Set the callback function for a source. + * Sets the callback function for a source. **/ void g_source_set_callback (GSource *source, @@ -1113,7 +1113,7 @@ g_source_set_callback (GSource *source, * @source: a #GSource * @priority: the new priority. * - * Set the priority of a source. While the main loop is being + * Sets the priority of a source. While the main loop is being * run, a source will **/ void @@ -1154,7 +1154,7 @@ g_source_set_priority (GSource *source, * g_source_get_priority: * @source: a #GSource * - * Gets the priority of a surce + * Gets the priority of a source. * * Return value: the priority of the source **/ @@ -1203,7 +1203,7 @@ g_source_set_can_recurse (GSource *source, * @source: a #GSource * * Checks whether a source is allowed to be called recursively. - * see g_source_set_can_recurse. + * see g_source_set_can_recurse(). * * Return value: whether recursion is allowed. **/ @@ -1718,7 +1718,7 @@ g_main_context_acquire (GMainContext *context) * g_main_context_release: * @context: a #GMainContext * - * Release ownership of a context previously acquired by this thread + * Releases ownership of a context previously acquired by this thread * with g_main_context_acquire(). If the context was acquired multiple * times, the only release ownership when g_main_context_release() * is called as many times as it was acquired. @@ -1765,10 +1765,9 @@ g_main_context_release (GMainContext *context) * @mutex: a mutex, currently held * * Tries to become the owner of the specified context, - * as with g_main_context_acquire. But if another thread - * is the owner, atomically drop @mutex and wait on - * @cond until wait until that owner releases - * ownership or until @cond is signaled, then + * as with g_main_context_acquire(). But if another thread + * is the owner, atomically drop @mutex and wait on @cond until + * that owner releases ownership or until @cond is signaled, then * try again (once) to become the owner. * * Return value: %TRUE if the operation succeeded, and @@ -2028,7 +2027,7 @@ g_main_context_query (GMainContext *context, * g_main_context_query() * @n_fds: return value of g_main_context_query() * - * Pass the results of polling back to the main loop. + * Passes the results of polling back to the main loop. * * Return value: %TRUE if some sources are ready to be dispatched. **/ @@ -2137,7 +2136,7 @@ g_main_context_check (GMainContext *context, * g_main_context_dispatch: * @context: a #GMainContext * - * Dispatch all pending sources() + * Dispatches all pending sources. **/ void g_main_context_dispatch (GMainContext *context) @@ -2242,7 +2241,7 @@ g_main_context_iterate (GMainContext *context, * g_main_context_pending: * @context: a #GMainContext (if %NULL, the default context will be used) * - * Check if any sources have pending events for the given context. + * Checks if any sources have pending events for the given context. * * Return value: %TRUE if events are pending. **/ @@ -2266,7 +2265,7 @@ g_main_context_pending (GMainContext *context) * @context: a #GMainContext (if %NULL, the default context will be used) * @may_block: whether the call may block. * - * Run a single iteration for the given main loop. This involves + * Runs a single iteration for the given main loop. This involves * checking to see if any event sources are ready to be processed, * then if no events sources are ready and @may_block is %TRUE, waiting * for a source to become ready, then dispatching the highest priority @@ -2295,13 +2294,13 @@ g_main_context_iteration (GMainContext *context, gboolean may_block) /** * g_main_loop_new: * @context: a #GMainContext (if %NULL, the default context will be used). - * @is_running: set to TRUE to indicate that the loop is running. This + * @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. + * %TRUE anyway. * - * Create a new #GMainLoop structure + * Creates a new #GMainLoop structure. * - * Return value: + * Return value: a new #GMainLoop. **/ GMainLoop * g_main_loop_new (GMainContext *context, @@ -2326,7 +2325,7 @@ g_main_loop_new (GMainContext *context, * g_main_loop_ref: * @loop: a #GMainLoop * - * Increase the reference count on a #GMainLoop object by one. + * Increases the reference count on a #GMainLoop object by one. * * Return value: @loop **/ @@ -2381,7 +2380,7 @@ g_main_loop_unref (GMainLoop *loop) * g_main_loop_run: * @loop: a #GMainLoop * - * Run a main loop until g_main_quit() is called on the loop. + * Runs a main loop until g_main_quit() is called on the loop. * If this is called for the thread of the loop's #GMainContext, * it will process events from the loop, otherwise it will * simply wait. @@ -2487,7 +2486,7 @@ g_main_loop_quit (GMainLoop *loop) * g_main_loop_is_running: * @loop: a #GMainLoop. * - * Check to see if the main loop is currently being run via g_main_run() + * Checks to see if the main loop is currently being run via g_main_run(). * * Return value: %TRUE if the mainloop is currently being run. **/ @@ -2600,8 +2599,8 @@ g_main_context_poll (GMainContext *context, * the same as the priority used for g_source_attach() to ensure that the * file descriptor is polled whenever the results may be needed. * - * Add a file descriptor to the set of file descriptors polled * for - * this context. This will very seldom be used directly. Instead + * Adds a file descriptor to the set of file descriptors polled for + * this context. This will very seldomly be used directly. Instead * a typical event source will use g_source_add_poll() instead. **/ void @@ -2674,7 +2673,7 @@ g_main_context_add_poll_unlocked (GMainContext *context, * @context:a #GMainContext * @fd: a #GPollFD descriptor previously added with g_main_context_add_poll() * - * Remove file descriptor from the set of file descriptors to be + * Removes file descriptor from the set of file descriptors to be * polled for a particular context. **/ void @@ -2772,8 +2771,9 @@ g_source_get_current_time (GSource *source, * @func: the function to call to poll all file descriptors * * Sets the function to use to handle polling of file descriptors. It - * will be used instead of the poll() system call (or GLib's - * replacement function, which is used where poll() isn't available). + * will be used instead of the <function>poll()</function> system call + * (or GLib's replacement function, which is used where + * <function>poll()</function> isn't available). * * This function could possibly be used to integrate the GLib event * loop with an external event loop. @@ -2807,7 +2807,7 @@ g_main_context_set_poll_func (GMainContext *context, * g_main_context_get_poll_func: * @context: a #GMainContext * - * Gets the poll function set by g_main_context_set_poll_func() + * Gets the poll function set by g_main_context_set_poll_func(). * * Return value: the poll function **/ @@ -2850,8 +2850,8 @@ g_main_context_wakeup_unlocked (GMainContext *context) * g_main_context_wakeup: * @context: a #GMainContext * - * If @context is currently waiting in a poll(), interrupt - * the poll(), and continue the iteration process. + * If @context is currently waiting in a <function>poll()</function>, interrupt + * the <function>poll()</function>, and continue the iteration process. **/ void g_main_context_wakeup (GMainContext *context) @@ -2981,13 +2981,13 @@ g_timeout_dispatch (GSource *source, * g_timeout_source_new: * @interval: the timeout interval in milliseconds. * - * Create a new timeout source. + * Creates a new timeout source. * * The source will not initially be associated with any #GMainContext * and must be added to one with g_source_attach() before it will be * executed. * - * Return value: the newly create timeout source + * Return value: the newly-created timeout source **/ GSource * g_timeout_source_new (guint interval) @@ -3007,16 +3007,16 @@ g_timeout_source_new (guint interval) /** * g_timeout_add_full: * @priority: the priority of the idle source. Typically this will be in the - * range btweeen #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. * @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 * @notify: function to call when the idle is removed, or %NULL * * Sets a function to be called at regular intervals, with the given * priority. The function is called repeatedly until it returns - * FALSE, at which point the timeout is automatically destroyed and + * %FALSE, at which point the timeout is automatically destroyed and * the function will not be called again. The @notify function is * called when the timeout is destroyed. The first call to the * function will be at the end of the first @interval. @@ -3056,13 +3056,13 @@ 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 * * 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 + * until it returns %FALSE, at which point the timeout is automatically * destroyed and the function will not be called again. The @notify * function is called when the timeout is destroyed. The first call * to the function will be at the end of the first @interval. @@ -3119,13 +3119,13 @@ g_idle_dispatch (GSource *source, /** * g_idle_source_new: * - * Create a new idle source. + * Creates a new idle source. * * The source will not initially be associated with any #GMainContext * and must be added to one with g_source_attach() before it will be * executed. * - * Return value: the newly created idle source + * Return value: the newly-created idle source **/ GSource * g_idle_source_new (void) @@ -3142,7 +3142,7 @@ g_idle_source_new (void) * @notify: 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 %FALSE it is automatically * removed from the list of event sources and will not be called again. * * Return value: the id of the event source. @@ -3178,7 +3178,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 - * returns FALSE it is automatically removed from the list of event + * returns %FALSE it is automatically removed from the list of event * sources and will not be called again. * * Return value: the id of the event source. diff --git a/glib/gshell.c b/glib/gshell.c index 87ebaff6f..399aec431 100644 --- a/glib/gshell.c +++ b/glib/gshell.c @@ -223,7 +223,7 @@ g_shell_quote (const gchar *unquoted_string) * would produce (the variables, backticks, etc. will be passed * through literally instead of being expanded). This function is * guaranteed to succeed if applied to the result of - * g_shell_quote(). If it fails, it returns NULL and sets the + * g_shell_quote(). If it fails, it returns %NULL and sets the * error. The @quoted_string need not actually contain quoted or * escaped text; g_shell_unquote() simply goes through the string and * unquotes/unescapes anything that the shell would. Both single and @@ -581,7 +581,7 @@ tokenize_command_line (const gchar *command_line, * literally. Possible errors are those from the #G_SHELL_ERROR * domain. Free the returned vector with g_strfreev(). * - * Return value: TRUE on success, FALSE if error set + * Return value: %TRUE on success, %FALSE if error set **/ gboolean g_shell_parse_argv (const gchar *command_line, diff --git a/glib/gspawn-win32.c b/glib/gspawn-win32.c index 17a98fc60..0208c622a 100644 --- a/glib/gspawn-win32.c +++ b/glib/gspawn-win32.c @@ -124,19 +124,19 @@ g_spawn_error_quark (void) /** * g_spawn_async: - * @working_directory: child's current working directory, or NULL to inherit parent's + * @working_directory: child's current working directory, or %NULL to inherit parent's * @argv: child's argument vector - * @envp: child's environment, or NULL to inherit parent's + * @envp: child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags - * @child_setup: function to run in the child just before exec() + * @child_setup: function to run in the child just before <function>exec()</function> * @user_data: user data for @child_setup - * @child_pid: return location for child process ID, or NULL + * @child_pid: return location for child process ID, or %NULL * @error: return location for error * * See g_spawn_async_with_pipes() for a full description; this function * simply calls the g_spawn_async_with_pipes() without any pipes. * - * Return value: TRUE on success, FALSE if error is set + * Return value: %TRUE on success, %FALSE if error is set **/ gboolean g_spawn_async (const gchar *working_directory, @@ -219,29 +219,29 @@ read_data (GString *str, /** * g_spawn_sync: - * @working_directory: child's current working directory, or NULL to inherit parent's + * @working_directory: child's current working directory, or %NULL to inherit parent's * @argv: child's argument vector - * @envp: child's environment, or NULL to inherit parent's + * @envp: child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags - * @child_setup: function to run in the child just before exec() + * @child_setup: function to run in the child just before <function>exec()</function> * @user_data: user data for @child_setup * @standard_output: return location for child output * @standard_error: return location for child error messages - * @exit_status: child exit status, as returned by waitpid() + * @exit_status: child exit status, as returned by <function>waitpid()</function> * @error: return location for error * * Executes a child synchronously (waits for the child to exit before returning). * All output from the child is stored in @standard_output and @standard_error, - * if those parameters are non-NULL. If @exit_status is non-NULL, the exit status - * of the child is stored there as it would be by waitpid(); standard UNIX - * macros such as WIFEXITED() and WEXITSTATUS() must be used to evaluate the + * if those parameters are non-%NULL. If @exit_status is non-%NULL, the exit status + * of the child is stored there as it would be returned by <function>waitpid()</function>; standard UNIX + * macros such as <function>WIFEXITED()</function> and <function>WEXITSTATUS()</function> must be used to evaluate the * exit status. If an error occurs, no data is returned in @standard_output, * @standard_error, or @exit_status. * * This function calls g_spawn_async_with_pipes() internally; see that function * for full details on the other parameters. * - * Return value: TRUE on success, FALSE if an error was set. + * Return value: %TRUE on success, %FALSE if an error was set. **/ gboolean g_spawn_sync (const gchar *working_directory, @@ -453,16 +453,16 @@ g_spawn_sync (const gchar *working_directory, /** * g_spawn_async_with_pipes: - * @working_directory: child's current working directory, or NULL to inherit parent's + * @working_directory: child's current working directory, or %NULL to inherit parent's * @argv: child's argument vector - * @envp: child's environment, or NULL to inherit parent's + * @envp: child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags - * @child_setup: function to run in the child just before exec() + * @child_setup: function to run in the child just before <function>exec()</function> * @user_data: user data for @child_setup - * @child_pid: return location for child process ID, or NULL - * @standard_input: return location for file descriptor to write to child's stdin, or NULL - * @standard_output: return location for file descriptor to read child's stdout, or NULL - * @standard_error: return location for file descriptor to read child's stderr, or NULL + * @child_pid: return location for child process ID, or %NULL + * @standard_input: return location for file descriptor to write to child's stdin, or %NULL + * @standard_output: return location for file descriptor to read child's stdout, or %NULL + * @standard_error: return location for file descriptor to read child's stderr, or %NULL * @error: return location for error * * Executes a child program asynchronously (your program will not @@ -471,51 +471,53 @@ g_spawn_sync (const gchar *working_directory, * should be a %NULL-terminated array of strings, to be passed as the * argument vector for the child. The first string in @argv is of * course the name of the program to execute. By default, the name of - * the program must be a full path; the PATH shell variable will only + * the program must be a full path; the <envvar>PATH</envvar> shell variable will only * be searched if you pass the %G_SPAWN_SEARCH_PATH flag. * * @envp is a %NULL-terminated array of strings, where each string * has the form <literal>KEY=VALUE</literal>. This will become - * the child's environment. If @envp is NULL, the child inherits its + * the child's environment. If @envp is %NULL, the child inherits its * parent's environment. * * @flags should be the bitwise OR of any flags you want to affect the * function's behavior. The %G_SPAWN_DO_NOT_REAP_CHILD means that the - * child will not be automatically reaped; you must call waitpid() or - * handle SIGCHLD yourself, or the child will become a zombie. - * %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file - * descriptors will be inherited by the child; otherwise all - * descriptors except stdin/stdout/stderr will be closed before - * calling exec() in the child. %G_SPAWN_SEARCH_PATH means that - * <literal>argv[0]</literal> need not be an absolute path, it - * will be looked for in the user's PATH. %G_SPAWN_STDOUT_TO_DEV_NULL - * means that the child's standad output will be discarded, instead - * of going to the same location as the parent's standard output. - * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error - * will be discarded. %G_SPAWN_CHILD_INHERITS_STDIN means that + * child will not be automatically reaped; you must call + * <function>waitpid()</function> or handle %SIGCHLD yourself, or the + * child will become a zombie. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means + * that the parent's open file descriptors will be inherited by the child; + * otherwise all descriptors except stdin/stdout/stderr will be closed before + * calling <function>exec()</function> in the child. %G_SPAWN_SEARCH_PATH + * means that <literal>argv[0]</literal> need not be an absolute path, it + * will be looked for in the user's <envvar>PATH</envvar>. + * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output + * will be discarded, instead of going to the same location as the parent's + * standard output. %G_SPAWN_STDERR_TO_DEV_NULL means that the child's + * standard error will be discarded. %G_SPAWN_CHILD_INHERITS_STDIN means that * the child will inherit the parent's standard input (by default, * the child's standard input is attached to /dev/null). * * @child_setup and @user_data are a function and user data to be * called in the child after GLib has performed all the setup it plans * to perform (including creating pipes, closing file descriptors, - * etc.) but before calling exec(). That is, @child_setup is called - * just before calling exec() in the child. Obviously actions taken in - * this function will only affect the child, not the parent. + * etc.) but before calling <function>exec()</function>. That is, @child_setup + * is called just before calling <function>exec()</function> in the child. + * Obviously actions taken in this function will only affect the child, not + * the parent. * - * If non-NULL, @child_pid will be filled with the child's process + * If non-%NULL, @child_pid will be filled with the child's process * ID. You can use the process ID to send signals to the child, or - * to waitpid() if you specified the %G_SPAWN_DO_NOT_REAP_CHILD flag. + * to <function>waitpid()</function> if you specified the + * %G_SPAWN_DO_NOT_REAP_CHILD flag. * - * If non-NULL, the @standard_input, @standard_output, @standard_error + * If non-%NULL, the @standard_input, @standard_output, @standard_error * locations will be filled with file descriptors for writing to the child's * standard input or reading from its standard output or standard error. * The caller of g_spawn_async_with_pipes() must close these file descriptors - * when they are no longer in use. If these parameters are NULL, the + * when they are no longer in use. If these parameters are %NULL, the * corresponding pipe won't be created. * - * @error can be NULL to ignore errors, or non-NULL to report errors. - * If an error is set, the function returns FALSE. Errors + * @error can be %NULL to ignore errors, or non-%NULL to report errors. + * If an error is set, the function returns %FALSE. Errors * are reported even if they occur in the child (for example if the * executable in <literal>argv[0]</literal> is not found). Typically * the <literal>message</literal> field of returned errors should be displayed @@ -524,7 +526,7 @@ g_spawn_sync (const gchar *working_directory, * If an error occurs, @child_pid, @standard_input, @standard_output, * and @standard_error will not be filled with valid values. * - * Return value: TRUE on success, FALSE if an error was set + * Return value: %TRUE on success, %FALSE if an error was set **/ gboolean g_spawn_async_with_pipes (const gchar *working_directory, @@ -583,7 +585,7 @@ g_spawn_async_with_pipes (const gchar *working_directory, * appropriate. Possible errors are those from g_spawn_sync() and those * from g_shell_parse_argv(). * - * Return value: TRUE on success, FALSE if an error was set + * Return value: %TRUE on success, %FALSE if an error was set **/ gboolean g_spawn_command_line_sync (const gchar *command_line, @@ -630,7 +632,7 @@ g_spawn_command_line_sync (const gchar *command_line, * consider using g_spawn_async() directly if appropriate. Possible * errors are those from g_shell_parse_argv() and g_spawn_async(). * - * Return value: TRUE on success, FALSE if error is set. + * Return value: %TRUE on success, %FALSE if error is set. **/ gboolean g_spawn_command_line_async (const gchar *command_line, @@ -762,7 +764,7 @@ do_exec (gboolean dont_wait, /* Call user function just before we execute the helper program, * which executes the program. Dunno what's the usefulness of this. * A child setup function used on Unix probably isn't of much use - * as such on Win32, anyhow. + * as such on Win32, anyhow */ if (child_setup) { diff --git a/glib/gspawn.c b/glib/gspawn.c index fd580b91b..4cce1728d 100644 --- a/glib/gspawn.c +++ b/glib/gspawn.c @@ -72,19 +72,19 @@ g_spawn_error_quark (void) /** * g_spawn_async: - * @working_directory: child's current working directory, or NULL to inherit parent's + * @working_directory: child's current working directory, or %NULL to inherit parent's * @argv: child's argument vector - * @envp: child's environment, or NULL to inherit parent's + * @envp: child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags - * @child_setup: function to run in the child just before exec() + * @child_setup: function to run in the child just before <function>exec()</function> * @user_data: user data for @child_setup - * @child_pid: return location for child process ID, or NULL + * @child_pid: return location for child process ID, or %NULL * @error: return location for error * * See g_spawn_async_with_pipes() for a full description; this function * simply calls the g_spawn_async_with_pipes() without any pipes. * - * Return value: TRUE on success, FALSE if error is set + * Return value: %TRUE on success, %FALSE if error is set **/ gboolean g_spawn_async (const gchar *working_directory, @@ -167,29 +167,30 @@ read_data (GString *str, /** * g_spawn_sync: - * @working_directory: child's current working directory, or NULL to inherit parent's + * @working_directory: child's current working directory, or %NULL to inherit parent's * @argv: child's argument vector - * @envp: child's environment, or NULL to inherit parent's + * @envp: child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags - * @child_setup: function to run in the child just before exec() + * @child_setup: function to run in the child just before <function>exec()</function> * @user_data: user data for @child_setup * @standard_output: return location for child output * @standard_error: return location for child error messages - * @exit_status: child exit status, as returned by waitpid() + * @exit_status: child exit status, as returned by <function>waitpid()</function> * @error: return location for error * * Executes a child synchronously (waits for the child to exit before returning). * All output from the child is stored in @standard_output and @standard_error, - * if those parameters are non-NULL. If @exit_status is non-NULL, the exit status - * of the child is stored there as it would be by waitpid(); standard UNIX - * macros such as WIFEXITED() and WEXITSTATUS() must be used to evaluate the - * exit status. If an error occurs, no data is returned in @standard_output, - * @standard_error, or @exit_status. + * if those parameters are non-%NULL. If @exit_status is non-%NULL, the exit + * status of the child is stored there as it would be returned by + * <function>waitpid()</function>; standard UNIX macros such as + * <function>WIFEXITED()</function> and <function>WEXITSTATUS()</function> + * must be used to evaluate the exit status. If an error occurs, no data is + * returned in @standard_output, @standard_error, or @exit_status. * * This function calls g_spawn_async_with_pipes() internally; see that function * for full details on the other parameters. * - * Return value: TRUE on success, FALSE if an error was set. + * Return value: %TRUE on success, %FALSE if an error was set. **/ gboolean g_spawn_sync (const gchar *working_directory, @@ -402,16 +403,16 @@ g_spawn_sync (const gchar *working_directory, /** * g_spawn_async_with_pipes: - * @working_directory: child's current working directory, or NULL to inherit parent's + * @working_directory: child's current working directory, or %NULL to inherit parent's * @argv: child's argument vector - * @envp: child's environment, or NULL to inherit parent's + * @envp: child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags - * @child_setup: function to run in the child just before exec() + * @child_setup: function to run in the child just before <function>exec()</function> * @user_data: user data for @child_setup - * @child_pid: return location for child process ID, or NULL - * @standard_input: return location for file descriptor to write to child's stdin, or NULL - * @standard_output: return location for file descriptor to read child's stdout, or NULL - * @standard_error: return location for file descriptor to read child's stderr, or NULL + * @child_pid: return location for child process ID, or %NULL + * @standard_input: return location for file descriptor to write to child's stdin, or %NULL + * @standard_output: return location for file descriptor to read child's stdout, or %NULL + * @standard_error: return location for file descriptor to read child's stderr, or %NULL * @error: return location for error * * Executes a child program asynchronously (your program will not @@ -420,26 +421,28 @@ g_spawn_sync (const gchar *working_directory, * should be a %NULL-terminated array of strings, to be passed as the * argument vector for the child. The first string in @argv is of * course the name of the program to execute. By default, the name of - * the program must be a full path; the PATH shell variable will only - * be searched if you pass the %G_SPAWN_SEARCH_PATH flag. + * the program must be a full path; the <envvar>PATH</envvar> shell variable + * will only be searched if you pass the %G_SPAWN_SEARCH_PATH flag. * * @envp is a %NULL-terminated array of strings, where each string * has the form <literal>KEY=VALUE</literal>. This will become - * the child's environment. If @envp is NULL, the child inherits its + * the child's environment. If @envp is %NULL, the child inherits its * parent's environment. * * @flags should be the bitwise OR of any flags you want to affect the * function's behavior. The %G_SPAWN_DO_NOT_REAP_CHILD means that the - * child will not be automatically reaped; you must call waitpid() or - * handle SIGCHLD yourself, or the child will become a zombie. + * child will not be automatically reaped; you must call + * <function>waitpid()</function> or handle %SIGCHLD yourself, or the + * child will become a zombie. * %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file * descriptors will be inherited by the child; otherwise all * descriptors except stdin/stdout/stderr will be closed before - * calling exec() in the child. %G_SPAWN_SEARCH_PATH means that - * <literal>argv[0]</literal> need not be an absolute path, it - * will be looked for in the user's PATH. %G_SPAWN_STDOUT_TO_DEV_NULL - * means that the child's standad output will be discarded, instead - * of going to the same location as the parent's standard output. + * calling <function>exec()</function> in the child. %G_SPAWN_SEARCH_PATH + * means that <literal>argv[0]</literal> need not be an absolute path, it + * will be looked for in the user's <envvar>PATH</envvar>. + * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standad output will + * be discarded, instead of going to the same location as the parent's + * standard output. * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error * will be discarded. %G_SPAWN_CHILD_INHERITS_STDIN means that * the child will inherit the parent's standard input (by default, @@ -453,23 +456,25 @@ g_spawn_sync (const gchar *working_directory, * @child_setup and @user_data are a function and user data to be * called in the child after GLib has performed all the setup it plans * to perform (including creating pipes, closing file descriptors, - * etc.) but before calling exec(). That is, @child_setup is called - * just before calling exec() in the child. Obviously actions taken in - * this function will only affect the child, not the parent. + * etc.) but before calling <function>exec()</function>. That is, + * @child_setup is called just before calling <function>exec()</function> + * in the child. Obviously actions taken in this function will only affect + * the child, not the parent. * - * If non-NULL, @child_pid will be filled with the child's process + * If non-%NULL, @child_pid will be filled with the child's process * ID. You can use the process ID to send signals to the child, or - * to waitpid() if you specified the %G_SPAWN_DO_NOT_REAP_CHILD flag. + * to <function>waitpid()</function> if you specified the + * %G_SPAWN_DO_NOT_REAP_CHILD flag. * - * If non-NULL, the @standard_input, @standard_output, @standard_error + * If non-%NULL, the @standard_input, @standard_output, @standard_error * locations will be filled with file descriptors for writing to the child's * standard input or reading from its standard output or standard error. * The caller of g_spawn_async_with_pipes() must close these file descriptors - * when they are no longer in use. If these parameters are NULL, the + * when they are no longer in use. If these parameters are %NULL, the * corresponding pipe won't be created. * - * @error can be NULL to ignore errors, or non-NULL to report errors. - * If an error is set, the function returns FALSE. Errors + * @error can be %NULL to ignore errors, or non-%NULL to report errors. + * If an error is set, the function returns %FALSE. Errors * are reported even if they occur in the child (for example if the * executable in <literal>argv[0]</literal> is not found). Typically * the <literal>message</literal> field of returned errors should be displayed @@ -478,7 +483,7 @@ g_spawn_sync (const gchar *working_directory, * If an error occurs, @child_pid, @standard_input, @standard_output, * and @standard_error will not be filled with valid values. * - * Return value: TRUE on success, FALSE if an error was set + * Return value: %TRUE on success, %FALSE if an error was set **/ gboolean g_spawn_async_with_pipes (const gchar *working_directory, @@ -538,7 +543,7 @@ g_spawn_async_with_pipes (const gchar *working_directory, * appropriate. Possible errors are those from g_spawn_sync() and those * from g_shell_parse_argv(). * - * Return value: TRUE on success, FALSE if an error was set + * Return value: %TRUE on success, %FALSE if an error was set **/ gboolean g_spawn_command_line_sync (const gchar *command_line, @@ -585,7 +590,7 @@ g_spawn_command_line_sync (const gchar *command_line, * consider using g_spawn_async() directly if appropriate. Possible * errors are those from g_shell_parse_argv() and g_spawn_async(). * - * Return value: TRUE on success, FALSE if error is set. + * Return value: %TRUE on success, %FALSE if error is set. **/ gboolean g_spawn_command_line_async (const gchar *command_line, diff --git a/glib/gtree.c b/glib/gtree.c index e2d717ed1..0c414ffa0 100644 --- a/glib/gtree.c +++ b/glib/gtree.c @@ -193,7 +193,7 @@ g_tree_new (GCompareFunc key_compare_func) /** * g_tree_new_with_data: - * @key_compare_func: qsort()-style comparison function. + * @key_compare_func: <function>qsort()</function>-style comparison function. * @key_compare_data: data to pass to comparison function. * * Creates a new #GTree with a comparison function that accepts user data. @@ -213,13 +213,13 @@ g_tree_new_with_data (GCompareDataFunc key_compare_func, /** * g_tree_new_full: - * @key_compare_func: qsort()-style comparison function. + * @key_compare_func: <function>qsort()</function>-style comparison function. * @key_compare_data: data to pass to comparison function. * @key_destroy_func: a function to free the memory allocated for the key - * used when removing the entry from the #GTree or #NULL if you don't + * used when removing the entry from the #GTree or %NULL if you don't * want to supply such a function. * @value_destroy_func: a function to free the memory allocated for the - * value used when removing the entry from the #GTree or #NULL if you + * value used when removing the entry from the #GTree or %NULL if you * don't want to supply such a function. * * Creates a new #GTree like g_tree_new() and allows to specify functions @@ -340,7 +340,7 @@ g_tree_replace (GTree *tree, * Removes a key/value pair from a #GTree. * * If the #GTree was created using g_tree_new_full(), the key and value - * are freed using the supplied @destroy_functions, otherwise you have to + * are freed using the supplied destroy functions, otherwise you have to * make sure that any dynamically allocated values are freed yourself. **/ void @@ -437,7 +437,7 @@ g_tree_lookup_extended (GTree *tree, * g_tree_foreach: * @tree: a #GTree. * @func: the function to call for each node visited. If this function - * returns TRUE, the traversal is stopped. + * returns %TRUE, the traversal is stopped. * @user_data: user data to pass to the function. * * Calls the given function for each of the key/value pairs in the #GTree. @@ -466,12 +466,12 @@ g_tree_foreach (GTree *tree, * g_tree_traverse: * @tree: a #GTree. * @traverse_func: the function to call for each node visited. If this - * function returns TRUE, the traversal is stopped. + * function returns %TRUE, the traversal is stopped. * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, * %G_PRE_ORDER and %G_POST_ORDER. * @user_data: user data to pass to the function. * - * Calls the given function for each node in the GTree. This function is + * Calls the given function for each node in the #GTree. This function is * deprecated, since the order of a balanced tree is somewhat arbitrary. * If you just want to visit all nodes in sorted order, use g_tree_foreach() * instead. If you really need to visit nodes in a different order, consider |