From d761fb4b3b8347e8fea51a40269031ed4ec1a303 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 2 Oct 2001 23:09:51 +0000 Subject: [PATCH] documentation update. add documentation. update docs. Remove references to * glib/gstrfuncs.c, glib/giochannel.c: documentation update. * glib/gqueue.c: add documentation. * glib/tmpl/iochannel.sgml, glib/tmpl/macros_misc.sgml, glib/tmpl/queue.sgml: update docs. * glib/tmpl/modules.sgml, glib/tmpl/threads.sgml: Remove references to glib-config. --- ChangeLog | 6 ++ ChangeLog.pre-2-0 | 6 ++ ChangeLog.pre-2-10 | 6 ++ ChangeLog.pre-2-12 | 6 ++ ChangeLog.pre-2-2 | 6 ++ ChangeLog.pre-2-4 | 6 ++ ChangeLog.pre-2-6 | 6 ++ ChangeLog.pre-2-8 | 6 ++ docs/reference/ChangeLog | 8 +++ docs/reference/glib/tmpl/iochannels.sgml | 2 +- docs/reference/glib/tmpl/macros_misc.sgml | 51 +++++++++----- docs/reference/glib/tmpl/modules.sgml | 4 +- docs/reference/glib/tmpl/patterns.sgml | 87 +++++++++++++++++++++++ docs/reference/glib/tmpl/queue.sgml | 34 +++++++-- docs/reference/glib/tmpl/threads.sgml | 7 +- glib/giochannel.c | 45 +++++++----- glib/gqueue.c | 105 ++++++++++++++++++++++++++++ glib/gstrfuncs.c | 112 +++++++++++++++--------------- 18 files changed, 397 insertions(+), 106 deletions(-) create mode 100644 docs/reference/glib/tmpl/patterns.sgml diff --git a/ChangeLog b/ChangeLog index 761e116..8d5967d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2001-10-02 Matthias Clasen + + * glib/gstrfuncs.c, glib/giochannel.c: documentation update. + + * glib/gqueue.c: add documentation. + 2001-10-02 Sven Neumann * glib/gstring.h (g_string_sprintfa): let the compatibility definition diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 761e116..8d5967d 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,9 @@ +2001-10-02 Matthias Clasen + + * glib/gstrfuncs.c, glib/giochannel.c: documentation update. + + * glib/gqueue.c: add documentation. + 2001-10-02 Sven Neumann * glib/gstring.h (g_string_sprintfa): let the compatibility definition diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 761e116..8d5967d 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,9 @@ +2001-10-02 Matthias Clasen + + * glib/gstrfuncs.c, glib/giochannel.c: documentation update. + + * glib/gqueue.c: add documentation. + 2001-10-02 Sven Neumann * glib/gstring.h (g_string_sprintfa): let the compatibility definition diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 761e116..8d5967d 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,3 +1,9 @@ +2001-10-02 Matthias Clasen + + * glib/gstrfuncs.c, glib/giochannel.c: documentation update. + + * glib/gqueue.c: add documentation. + 2001-10-02 Sven Neumann * glib/gstring.h (g_string_sprintfa): let the compatibility definition diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 761e116..8d5967d 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,9 @@ +2001-10-02 Matthias Clasen + + * glib/gstrfuncs.c, glib/giochannel.c: documentation update. + + * glib/gqueue.c: add documentation. + 2001-10-02 Sven Neumann * glib/gstring.h (g_string_sprintfa): let the compatibility definition diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 761e116..8d5967d 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,9 @@ +2001-10-02 Matthias Clasen + + * glib/gstrfuncs.c, glib/giochannel.c: documentation update. + + * glib/gqueue.c: add documentation. + 2001-10-02 Sven Neumann * glib/gstring.h (g_string_sprintfa): let the compatibility definition diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 761e116..8d5967d 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,9 @@ +2001-10-02 Matthias Clasen + + * glib/gstrfuncs.c, glib/giochannel.c: documentation update. + + * glib/gqueue.c: add documentation. + 2001-10-02 Sven Neumann * glib/gstring.h (g_string_sprintfa): let the compatibility definition diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 761e116..8d5967d 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,9 @@ +2001-10-02 Matthias Clasen + + * glib/gstrfuncs.c, glib/giochannel.c: documentation update. + + * glib/gqueue.c: add documentation. + 2001-10-02 Sven Neumann * glib/gstring.h (g_string_sprintfa): let the compatibility definition diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index ba27bd6..5cc1201 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,11 @@ +2001-10-02 Matthias Clasen + + * glib/tmpl/iochannel.sgml, glib/tmpl/macros_misc.sgml, + glib/tmpl/queue.sgml: update docs. + + * glib/tmpl/modules.sgml, glib/tmpl/threads.sgml: Remove + references to glib-config. + 2001-10-01 Matthias Clasen * glib/tmpl/iochannels.sgml, glib/tmpl/shell.sgml, diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml index 19b582f..f6d2d5a 100644 --- a/docs/reference/glib/tmpl/iochannels.sgml +++ b/docs/reference/glib/tmpl/iochannels.sgml @@ -295,7 +295,7 @@ Error codes returned by #GIOChannel operations. @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_OVERFLOW: Value too large for defined datatype. @G_IO_CHANNEL_ERROR_PIPE: Broken pipe. @G_IO_CHANNEL_ERROR_FAILED: Some other error. diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml index 2133f92..276a463 100644 --- a/docs/reference/glib/tmpl/macros_misc.sgml +++ b/docs/reference/glib/tmpl/macros_misc.sgml @@ -98,15 +98,6 @@ when compiling with the -pedantic option. - - -Expands to the GNU C const function attribute if the compiler is GNU C. -This enables optimization of the function. -See the GNU C documentation for details. - - - - Expands to the GNU C noreturn function attribute if the compiler is GNU C. @@ -129,9 +120,20 @@ It avoids possible compiler warnings. See the GNU C documentation for details. Expands to the GNU C pure function attribute if the compiler is GNU C. +Declaring a function as pure enables better optimization of the function. +A pure function has no effects except its return value and the return +value depends only on the parameters and/or global variables. See the GNU C documentation for details. + -FIXME: Explain what pure functions are. + + + +Expands to the GNU C const function attribute if the compiler is GNU C. +Declaring a function as const enables better optimization of the function. +A const function doesn't examine any values except its parameters, +and has no effects except its return value. +See the GNU C documentation for details. @@ -144,6 +146,12 @@ arguments, with the same syntax as printf(). It allows the compiler to type-check the arguments passed to the function. See the GNU C documentation for details. + +gint g_snprintf (gchar *string, + gulong n, + gchar const *format, + ...) G_GNUC_PRINTF (3, 4); + @format_idx: the index of the argument corresponding to the format string. (The arguments are numbered from 1). @@ -167,12 +175,19 @@ See the GNU C documentation for details. Expands to the GNU C format_arg function attribute if the compiler is GNU C. -This is used for declaring functions which take a variable number of -parameters, like printf() and -scanf(). See the GNU C documentation for details. - -FIXME: I can't find this in my GNU C documentation. Take out? +The format_arg function attribute specifies that a function takes a format +string for a printf(), scanf(), +strftime() or strfmon() style +function and modifies it, so that the result can be passed to a +printf(), scanf(), +strftime() or strfmon() style +function (with the remaining arguments to the format function the same as +they would have been for the unmodified string). +See the GNU C documentation for details. + +gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); + @arg_idx: the index of the argument. @@ -203,10 +218,10 @@ GNU C documentation for details. Expands to the GNU C no_instrument_function function attribute if -the compiler is GNU C. +the compiler is GNU C. Functions with this attribute will not be +instrumented for profiling, when the compiler is called with the + option. See the GNU C documentation for details. - -FIXME: Explain no_instrument_function. diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml index 028a694..f301201 100644 --- a/docs/reference/glib/tmpl/modules.sgml +++ b/docs/reference/glib/tmpl/modules.sgml @@ -14,8 +14,8 @@ an implementation of dlopen() (e.g. Linux/Sun), as well as -A program, which wants to use these functions must be linked to the -libraries output by the command glib-config --libs gmodule. +A program which wants to use these functions must be linked to the +libraries output by the command pkg-config --libs gmodule-2.0. diff --git a/docs/reference/glib/tmpl/patterns.sgml b/docs/reference/glib/tmpl/patterns.sgml new file mode 100644 index 0000000..4d7923d --- /dev/null +++ b/docs/reference/glib/tmpl/patterns.sgml @@ -0,0 +1,87 @@ + +Glob-style pattern matching + + + + + + + + + + + + + + + + + + + +@G_MATCH_ALL: +@G_MATCH_ALL_TAIL: +@G_MATCH_HEAD: +@G_MATCH_TAIL: +@G_MATCH_EXACT: +@G_MATCH_LAST: + + + + + + +@match_type: +@pattern_length: +@pattern: +@pattern_reversed: + + + + + + +@pattern: +@Returns: + + + + + + + +@pspec: + + + + + + + +@pspec: +@string_length: +@string: +@string_reversed: +@Returns: + + + + + + + +@pspec: +@string: +@Returns: + + + + + + + +@pattern: +@string: +@Returns: + + diff --git a/docs/reference/glib/tmpl/queue.sgml b/docs/reference/glib/tmpl/queue.sgml index 1f602c6..fc5bb53 100644 --- a/docs/reference/glib/tmpl/queue.sgml +++ b/docs/reference/glib/tmpl/queue.sgml @@ -2,12 +2,32 @@ Double-ended Queues - -Double-ended queue data structure +double-ended queue data structure - +The #GQueue structure and its associated functions provide a standard +queue data structure. Internally, #GQueue uses the same data structure as +#GList to store elements. + + +The data contained in each element can be either integer values, by using one +of the +Type Conversion Macros, +or simply pointers to any type of data. + + +To create a new #GQueue, use g_queue_new(). + + +To add elements, use g_queue_push_head(), g_queue_push_head_link(), +g_queue_push_tail() and g_queue_push_tail_link(). + + +To remove elements, use g_queue_pop_head() and g_queue_pop_tail(). + + +To free the entire queue, use g_queue_free(). @@ -17,12 +37,12 @@ Double-ended queue data structure - +Contains the public fields of a Queue. -@head: -@tail: -@length: +@head: a pointer to the first element of the queue. +@tail: a pointer to the last element of the queue. +@length: the number of elements in the queue. diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml index 1029c7e..6ee73ac 100644 --- a/docs/reference/glib/tmpl/threads.sgml +++ b/docs/reference/glib/tmpl/threads.sgml @@ -191,10 +191,9 @@ elements of @vtable are non-%NULL, then g_thread_init() will abort. To use g_thread_init() in your program, you have to link with the -libraries, that the command "glib-config --libs gthread" outputs. This -is not the case for all the other thread related functions of -GLib. Those can be used without having to link with the thread -libraries. +libraries that the command pkg-config --libs gthread-2.0 +outputs. This is not the case for all the other thread related functions of +GLib. Those can be used without having to link with the thread libraries. diff --git a/glib/giochannel.c b/glib/giochannel.c index 2cd6f58..fd952ed 100644 --- a/glib/giochannel.c +++ b/glib/giochannel.c @@ -333,7 +333,7 @@ g_io_channel_close (GIOChannel *channel) * flushed if @flush is %TRUE. The channel will not be freed until the * last reference is dropped using g_io_channel_unref(). * - * Return value: + * Return value: the status of the operation. **/ GIOStatus g_io_channel_shutdown (GIOChannel *channel, @@ -512,9 +512,11 @@ g_io_channel_get_buffer_condition (GIOChannel *channel) /** * g_io_channel_error_from_errno: - * @en: An errno error number, e.g. EINVAL + * @en: an errno error number, e.g. %EINVAL. * - * Return value: A #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL + * Converts an errno error number to a #GIOChannelError. + * + * Return value: a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL. **/ GIOChannelError g_io_channel_error_from_errno (gint en) @@ -682,11 +684,13 @@ g_io_channel_get_line_term (GIOChannel *channel, /** * g_io_channel_set_flags: - * @channel: a #GIOChannel - * @flags: the flags to set on the channel - * @error: A location to return an error of type #GIOChannelError + * @channel: a #GIOChannel. + * @flags: the flags to set on the channel. + * @error: A location to return an error of type #GIOChannelError. + * + * Sets flags on the channel. * - * Return value: + * Return value: the status of the operation. **/ GIOStatus g_io_channel_set_flags (GIOChannel *channel, @@ -761,12 +765,15 @@ g_io_channel_set_close_on_unref (GIOChannel *channel, /** * g_io_channel_get_close_on_unref: - * @channel: a #GIOChannel + * @channel: a #GIOChannel. * - * Return value: Whether the channel will be closedi on the final unref of - * the GIOChannel data structure. The default value of - * this is %TRUE for channels created by g_io_channel_new_file (), - * and %FALSE for all other channels. + * Returns whether the channel will be closed on the final unref of the + * #GIOChannel data structure. The default value of this is %TRUE for + * channels created by g_io_channel_new_file(), and %FALSE for all other + * channels. + * + * Return value: %TRUE if the channel will be closed on the final unref of + * the #GIOChannel data structure. **/ gboolean g_io_channel_get_close_on_unref (GIOChannel *channel) @@ -788,7 +795,7 @@ g_io_channel_get_close_on_unref (GIOChannel *channel) * * Replacement for g_io_channel_seek() with the new API. * - * Return value: + * Return value: the status of the operation. **/ GIOStatus g_io_channel_seek_position (GIOChannel* channel, @@ -966,9 +973,11 @@ g_io_channel_set_buffered (GIOChannel *channel, /** * g_io_channel_get_buffered: - * @channel: a #GIOChannel + * @channel: a #GIOChannel. + * + * Returns the buffering state of the channel. * - * Return Value: the buffering state of the channel + * Return Value: %TRUE if the @channel is buffered. **/ gboolean g_io_channel_get_buffered (GIOChannel *channel) @@ -1402,7 +1411,7 @@ g_io_channel_read_line (GIOChannel *channel, * * Read a line from a #GIOChannel, using a #GString as a buffer. * - * Return value: + * Return value: the status of the operation. **/ GIOStatus g_io_channel_read_line_string (GIOChannel *channel, @@ -1696,7 +1705,7 @@ g_io_channel_read_to_end (GIOChannel *channel, * * Replacement for g_io_channel_read() with the new API. * - * Return value: + * Return value: the status of the operation. **/ GIOStatus g_io_channel_read_chars (GIOChannel *channel, @@ -1880,7 +1889,7 @@ g_io_channel_read_unichar (GIOChannel *channel, * may only be made on a channel from which data has been read in the * cases described in the documentation for g_io_channel_set_encoding (). * - * Return value: + * Return value: the status of the operation. **/ GIOStatus g_io_channel_write_chars (GIOChannel *channel, diff --git a/glib/gqueue.c b/glib/gqueue.c index b15adb4..8c60933 100644 --- a/glib/gqueue.c +++ b/glib/gqueue.c @@ -35,6 +35,13 @@ G_LOCK_DEFINE_STATIC (queue_memchunk); static GMemChunk *queue_memchunk = NULL; static GTrashStack *free_queue_nodes = NULL; +/** + * g_queue_new: + * + * Creates a new #GQueue. + * + * Returns: a new #GQueue. + **/ GQueue* g_queue_new (void) { @@ -61,6 +68,12 @@ g_queue_new (void) return queue; } +/** + * g_queue_free: + * @queue: a #GQueue. + * + * Frees the memory allocated for the #GQueue. + **/ void g_queue_free (GQueue *queue) { @@ -78,6 +91,13 @@ g_queue_free (GQueue *queue) G_UNLOCK (queue_memchunk); } +/** + * g_queue_push_head: + * @queue: a #GQueue. + * @data: the data for the new element. + * + * Adds a new element at the head of the queue. + **/ void g_queue_push_head (GQueue *queue, gpointer data) @@ -90,6 +110,14 @@ g_queue_push_head (GQueue *queue, queue->length++; } +/** + * g_queue_push_head_link: + * @queue: a #GQueue. + * @link: a single #GList element, not a list with + * more than one element. + * + * Adds a new element at the head of the queue. + **/ void g_queue_push_head_link (GQueue *queue, GList *link) @@ -108,6 +136,13 @@ g_queue_push_head_link (GQueue *queue, queue->length++; } +/** + * g_queue_push_tail: + * @queue: a #GQueue. + * @data: the data for the new element. + * + * Adds a new element at the tail of the queue. + **/ void g_queue_push_tail (GQueue *queue, gpointer data) @@ -122,6 +157,14 @@ g_queue_push_tail (GQueue *queue, queue->length++; } +/** + * g_queue_push_tail_link: + * @queue: a #GQueue. + * @link: a single #GList element, not a list with + * more than one element. + * + * Adds a new element at the tail of the queue. + **/ void g_queue_push_tail_link (GQueue *queue, GList *link) @@ -140,6 +183,15 @@ g_queue_push_tail_link (GQueue *queue, queue->length++; } +/** + * g_queue_pop_head: + * @queue: a #GQueue. + * + * Removes the first element of the queue. + * + * Returns: the data of the first element in the queue, or %NULL if the queue + * is empty. + **/ gpointer g_queue_pop_head (GQueue *queue) { @@ -164,6 +216,15 @@ g_queue_pop_head (GQueue *queue) return NULL; } +/** + * g_queue_pop_head_link: + * @queue: a #GQueue. + * + * Removes the first element of the queue. + * + * Returns: the #GList element at the head of the queue, or %NULL if the queue + * is empty. + **/ GList* g_queue_pop_head_link (GQueue *queue) { @@ -189,6 +250,15 @@ g_queue_pop_head_link (GQueue *queue) return NULL; } +/** + * g_queue_pop_tail: + * @queue: a #GQueue. + * + * Removes the last element of the queue. + * + * Returns: the data of the last element in the queue, or %NULL if the queue + * is empty. + **/ gpointer g_queue_pop_tail (GQueue *queue) { @@ -213,6 +283,15 @@ g_queue_pop_tail (GQueue *queue) return NULL; } +/** + * g_queue_pop_tail_link: + * @queue: a #GQueue. + * + * Removes the last element of the queue. + * + * Returns: the #GList element at the tail of the queue, or %NULL if the queue + * is empty. + **/ GList* g_queue_pop_tail_link (GQueue *queue) { @@ -238,6 +317,14 @@ g_queue_pop_tail_link (GQueue *queue) return NULL; } +/** + * g_queue_is_empty: + * @queue: a #GQueue. + * + * Returns %TRUE if the queue is empty. + * + * Returns: %TRUE if the queue is empty. + **/ gboolean g_queue_is_empty (GQueue *queue) { @@ -246,6 +333,15 @@ g_queue_is_empty (GQueue *queue) return queue->head == NULL; } +/** + * g_queue_peek_head: + * @queue: a #GQueue. + * + * Returns the first element of the queue. + * + * Returns: the data of the first element in the queue, or %NULL if the queue + * is empty. + **/ gpointer g_queue_peek_head (GQueue *queue) { @@ -254,6 +350,15 @@ g_queue_peek_head (GQueue *queue) return queue->head ? queue->head->data : NULL; } +/** + * g_queue_peek_tail: + * @queue: a #GQueue. + * + * Returns the last element of the queue. + * + * Returns: the data of the last element in the queue, or %NULL if the queue + * is empty. + **/ gpointer g_queue_peek_tail (GQueue *queue) { diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 5fea809..d05360a 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -144,8 +144,8 @@ g_strnfill (gsize length, /** * g_stpcpy: - * @dest: destination buffer - * @src: source string + * @dest: destination buffer. + * @src: source string. * * Copies a nul-terminated string into the dest buffer, include the * trailing nul, and return a pointer to the trailing nul byte. @@ -996,15 +996,15 @@ g_strlcat (gchar *dest, /** * g_ascii_strdown: - * @str: a string + * @str: a string. * @len: length of @str in bytes, or -1 if @str is nul-terminated. * * Converts all upper case ASCII letters to lower case ASCII letters. * - * Return value: a newly allocated string, with all the upper case + * Return value: a newly-allocated string, with all the upper case * characters in @str converted to lower case, with - * semantics that exactly match g_ascii_tolower. (Note - * that this is unlike the old g_strdown, which modified + * semantics that exactly match g_ascii_tolower(). (Note + * that this is unlike the old g_strdown(), which modified * the string in place.) **/ gchar* @@ -1027,15 +1027,15 @@ g_ascii_strdown (const gchar *str, /** * g_ascii_strup: - * @str: a string + * @str: a string. * @len: length of @str in bytes, or -1 if @str is nul-terminated. * * Converts all lower case ASCII letters to upper case ASCII letters. * * Return value: a newly allocated string, with all the lower case * characters in @str converted to upper case, with - * semantics that exactly match g_ascii_toupper. (Note - * that this is unlike the old g_strup, which modified + * semantics that exactly match g_ascii_toupper(). (Note + * that this is unlike the old g_strup(), which modified * the string in place.) **/ gchar* @@ -1123,16 +1123,16 @@ g_strreverse (gchar *string) /** * g_ascii_tolower: - * @c: any character + * @c: any character. * * Convert a character to ASCII lower case. * - * Unlike the standard C library tolower function, this only + * Unlike the standard C library tolower() function, this only * recognizes standard ASCII letters and ignores the locale, returning * all non-ASCII characters unchanged, even if they are lower case * letters in a particular character set. Also unlike the standard * library function, this takes and returns a char, not an int, so - * don't call it on EOF but no need to worry about casting to guchar + * don't call it on %EOF but no need to worry about casting to #guchar * before passing a possibly non-ASCII character in. * * Return value: the result of converting @c to lower case. @@ -1147,16 +1147,16 @@ g_ascii_tolower (gchar c) /** * g_ascii_toupper: - * @c: any character + * @c: any character. * * Convert a character to ASCII upper case. * - * Unlike the standard C library toupper function, this only + * Unlike the standard C library toupper() function, this only * recognizes standard ASCII letters and ignores the locale, returning * all non-ASCII characters unchanged, even if they are upper case * letters in a particular character set. Also unlike the standard * library function, this takes and returns a char, not an int, so - * don't call it on EOF but no need to worry about casting to guchar + * don't call it on %EOF but no need to worry about casting to #guchar * before passing a possibly non-ASCII character in. * * Return value: the result of converting @c to upper case. @@ -1171,15 +1171,15 @@ g_ascii_toupper (gchar c) /** * g_ascii_digit_value: - * @c: an ASCII character + * @c: an ASCII character. * * Determines the numeric value of a character as a decimal - * digit. Differs from g_unichar_digit_value because it takes + * digit. Differs from g_unichar_digit_value() because it takes * a char, so there's no worry about sign extension if characters * are signed. * * Return value: If @c is a decimal digit (according to - * `g_ascii_isdigit'), its numeric value. Otherwise, -1. + * g_ascii_isdigit()), its numeric value. Otherwise, -1. **/ int g_ascii_digit_value (gchar c) @@ -1191,15 +1191,15 @@ g_ascii_digit_value (gchar c) /** * g_ascii_xdigit_value: - * @c: an ASCII character + * @c: an ASCII character. * * Determines the numeric value of a character as a hexidecimal - * digit. Differs from g_unichar_xdigit_value because it takes + * digit. Differs from g_unichar_xdigit_value() because it takes * a char, so there's no worry about sign extension if characters * are signed. * * Return value: If @c is a hex digit (according to - * `g_ascii_isxdigit'), its numeric value. Otherwise, -1. + * g_ascii_isxdigit()), its numeric value. Otherwise, -1. **/ int g_ascii_xdigit_value (gchar c) @@ -1213,12 +1213,12 @@ g_ascii_xdigit_value (gchar c) /** * g_ascii_strcasecmp: - * @s1: string to compare with @s2 - * @s2: string to compare with @s1 + * @s1: string to compare with @s2. + * @s2: string to compare with @s1. * * Compare two strings, ignoring the case of ASCII characters. * - * Unlike the BSD strcasecmp function, this only recognizes standard + * Unlike the BSD strcasecmp() function, this only recognizes standard * ASCII letters and ignores the locale, treating all non-ASCII * characters as if they are not letters. * @@ -1249,14 +1249,14 @@ g_ascii_strcasecmp (const gchar *s1, /** * g_ascii_strncasecmp: - * @s1: string to compare with @s2 - * @s2: string to compare with @s1 - * @n: number of characters to compare + * @s1: string to compare with @s2. + * @s2: string to compare with @s1. + * @n: number of characters to compare. * * Compare @s1 and @s2, ignoring the case of ASCII characters and any * characters after the first @n in each string. * - * Unlike the BSD strcasecmp function, this only recognizes standard + * Unlike the BSD strcasecmp() function, this only recognizes standard * ASCII letters and ignores the locale, treating all non-ASCII * characters as if they are not letters. * @@ -1569,7 +1569,7 @@ g_strchomp (gchar *string) * @string: a string to split. * @delimiter: a string which specifies the places at which to split the string. * The delimiter is not included in any of the resulting strings, unless - * max_tokens is reached. + * @max_tokens is reached. * @max_tokens: the maximum number of pieces to split @string into. If this is * less than 1, the string is split completely. * @@ -1584,8 +1584,8 @@ g_strchomp (gchar *string) * to represent empty elements, you'll need to check for the empty string * before calling g_strsplit(). * - * Return value: a newly-allocated %NULL-terminated array of strings. Use g_strfreev() - * to free it. + * Return value: a newly-allocated %NULL-terminated array of strings. Use + * g_strfreev() to free it. **/ gchar** g_strsplit (const gchar *string, @@ -1661,14 +1661,14 @@ g_strfreev (gchar **str_array) /** * g_strdupv: - * @str_array: %NULL-terminated array of strings + * @str_array: %NULL-terminated array of strings. * * Copies %NULL-terminated array of strings. The copy is a deep copy; * the new array should be freed by first freeing each string, then * the array itself. g_strfreev() does this for you. If called * on a %NULL value, g_strdupv() simply returns %NULL. * - * Return value: a new %NULL-terminated array of strings + * Return value: a new %NULL-terminated array of strings. **/ gchar** g_strdupv (gchar **str_array) @@ -1797,16 +1797,16 @@ g_strjoin (const gchar *separator, /** * g_strstr_len: - * @haystack: a string - * @haystack_len: The maximum length of haystack - * @needle: The string to search for. + * @haystack: a string. + * @haystack_len: the maximum length of @haystack. + * @needle: the string to search for. * - * Searches the string haystack for the first occurrence - * of the string needle, limiting the length of the search - * to haystack_len. + * Searches the string @haystack for the first occurrence + * of the string @needle, limiting the length of the search + * to @haystack_len. * - * Return value: A pointer to the found occurrence, or - * NULL if not found. + * Return value: a pointer to the found occurrence, or + * %NULL if not found. **/ gchar * g_strstr_len (const gchar *haystack, @@ -1850,15 +1850,15 @@ g_strstr_len (const gchar *haystack, } /** - * g_strrstr_len: - * @haystack: a nul-terminated string - * @needle: The nul-terminated string to search for. + * g_strrstr: + * @haystack: a nul-terminated string. + * @needle: the nul-terminated string to search for. * - * Searches the string haystack for the last occurrence - * of the string needle. + * Searches the string @haystack for the last occurrence + * of the string @needle. * - * Return value: A pointer to the found occurrence, or - * NULL if not found. + * Return value: a pointer to the found occurrence, or + * %NULL if not found. **/ gchar * g_strrstr (const gchar *haystack, @@ -1900,16 +1900,16 @@ g_strrstr (const gchar *haystack, /** * g_strrstr_len: - * @haystack: a nul-terminated string - * @haystack_len: The maximum length of haystack - * @needle: The nul-terminated string to search for. + * @haystack: a nul-terminated string. + * @haystack_len: the maximum length of @haystack. + * @needle: the nul-terminated string to search for. * - * Searches the string haystack for the last occurrence - * of the string needle, limiting the length of the search - * to haystack_len. + * Searches the string @haystack for the last occurrence + * of the string @needle, limiting the length of the search + * to @haystack_len. * - * Return value: A pointer to the found occurrence, or - * NULL if not found. + * Return value: a pointer to the found occurrence, or + * %NULL if not found. **/ gchar * g_strrstr_len (const gchar *haystack, -- 2.7.4