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

@@ -1,3 +1,9 @@
+2001-10-02  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
+
+	* glib/gqueue.c: add documentation.
+
 2001-10-02  Sven Neumann  <sven@gimp.org>
 
 	* glib/gstring.h (g_string_sprintfa): let the compatibility definition

ChangeLog.pre-2-0

@@ -1,3 +1,9 @@
+2001-10-02  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
+
+	* glib/gqueue.c: add documentation.
+
 2001-10-02  Sven Neumann  <sven@gimp.org>
 
 	* glib/gstring.h (g_string_sprintfa): let the compatibility definition

ChangeLog.pre-2-10

@@ -1,3 +1,9 @@
+2001-10-02  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
+
+	* glib/gqueue.c: add documentation.
+
 2001-10-02  Sven Neumann  <sven@gimp.org>
 
 	* glib/gstring.h (g_string_sprintfa): let the compatibility definition

ChangeLog.pre-2-12

@@ -1,3 +1,9 @@
+2001-10-02  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
+
+	* glib/gqueue.c: add documentation.
+
 2001-10-02  Sven Neumann  <sven@gimp.org>
 
 	* glib/gstring.h (g_string_sprintfa): let the compatibility definition

ChangeLog.pre-2-2

@@ -1,3 +1,9 @@
+2001-10-02  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
+
+	* glib/gqueue.c: add documentation.
+
 2001-10-02  Sven Neumann  <sven@gimp.org>
 
 	* glib/gstring.h (g_string_sprintfa): let the compatibility definition

ChangeLog.pre-2-4

@@ -1,3 +1,9 @@
+2001-10-02  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
+
+	* glib/gqueue.c: add documentation.
+
 2001-10-02  Sven Neumann  <sven@gimp.org>
 
 	* glib/gstring.h (g_string_sprintfa): let the compatibility definition

ChangeLog.pre-2-6

@@ -1,3 +1,9 @@
+2001-10-02  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
+
+	* glib/gqueue.c: add documentation.
+
 2001-10-02  Sven Neumann  <sven@gimp.org>
 
 	* glib/gstring.h (g_string_sprintfa): let the compatibility definition

ChangeLog.pre-2-8

@@ -1,3 +1,9 @@
+2001-10-02  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
+
+	* glib/gqueue.c: add documentation.
+
 2001-10-02  Sven Neumann  <sven@gimp.org>
 
 	* glib/gstring.h (g_string_sprintfa): let the compatibility definition

docs/reference/ChangeLog

@@ -1,3 +1,11 @@
+2001-10-02  Matthias Clasen  <matthiasc@poet.de>
+
+	* 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  <matthiasc@poet.de>
 
 	* glib/tmpl/iochannels.sgml, glib/tmpl/shell.sgml,

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.
 

docs/reference/glib/tmpl/macros_misc.sgml

@@ -98,15 +98,6 @@ when compiling with the <literal>-pedantic</literal> option.
 
 
 
-<!-- ##### MACRO G_GNUC_CONST ##### -->
-<para>
-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. 
-</para>
-
-
-
 <!-- ##### MACRO G_GNUC_NORETURN ##### -->
 <para>
 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.
 <!-- ##### MACRO G_GNUC_PURE ##### -->
 <para>
 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. 
+</para>
 
-FIXME: Explain what pure functions are.
+
+<!-- ##### MACRO G_GNUC_CONST ##### -->
+<para>
+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. 
 </para>
 
 
@@ -144,6 +146,12 @@ arguments, with the same syntax as <function>printf()</function>.
 It allows the compiler to type-check the arguments passed to the function.
 See the GNU C documentation for details. 
 </para>
+<informalexample><programlisting>
+gint g_snprintf (gchar  *string,
+                 gulong       n,
+                 gchar const *format,
+                 ...) G_GNUC_PRINTF (3, 4);
+</programlisting></informalexample>
 
 @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.
 <!-- ##### MACRO G_GNUC_FORMAT ##### -->
 <para>
 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
+The format_arg function attribute specifies that a function takes a format
-parameters, like <function>printf()</function> and
+string for a <function>printf()</function>, <function>scanf()</function>, 
-<function>scanf()</function>. See the GNU C documentation for details. 
+<function>strftime()</function> or <function>strfmon()</function> style
-
+function and modifies it, so that the result can be passed to a 
-FIXME: I can't find this in my GNU C documentation. Take out?
+<function>printf()</function>, <function>scanf()</function>, 
+<function>strftime()</function> or <function>strfmon()</function> 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. 
 </para>
+<informalexample><programlisting>
+gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
+</programlisting></informalexample>
 
 @arg_idx: the index of the argument.
 
@@ -203,10 +218,10 @@ GNU C documentation for details.
 <!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
 <para>
 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>-finstrument-functions</option> option.
 See the GNU C documentation for details. 
-
-FIXME: Explain no_instrument_function.
 </para>
 
 

docs/reference/glib/tmpl/modules.sgml

@@ -14,8 +14,8 @@ an implementation of <function>dlopen()</function> (e.g. Linux/Sun), as well as
 </para>
 
 <para>
-A program, which wants to use these functions must be linked to the
+A program which wants to use these functions must be linked to the
-libraries output by the command <command>glib-config --libs gmodule</command>.
+libraries output by the command <command>pkg-config --libs gmodule-2.0</command>.
 </para>
 
 <para>

docs/reference/glib/tmpl/patterns.sgml

@@ -0,0 +1,87 @@
+<!-- ##### SECTION Title ##### -->
+Glob-style pattern matching
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### ENUM GMatchType ##### -->
+<para>
+
+</para>
+
+@G_MATCH_ALL: 
+@G_MATCH_ALL_TAIL: 
+@G_MATCH_HEAD: 
+@G_MATCH_TAIL: 
+@G_MATCH_EXACT: 
+@G_MATCH_LAST: 
+
+<!-- ##### STRUCT GPatternSpec ##### -->
+<para>
+
+</para>
+
+@match_type: 
+@pattern_length: 
+@pattern: 
+@pattern_reversed: 
+
+<!-- ##### FUNCTION g_pattern_spec_new ##### -->
+<para>
+
+</para>
+
+@pattern: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_pattern_spec_free ##### -->
+<para>
+
+</para>
+
+@pspec: 
+
+
+<!-- ##### FUNCTION g_pattern_match ##### -->
+<para>
+
+</para>
+
+@pspec: 
+@string_length: 
+@string: 
+@string_reversed: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_pattern_match_string ##### -->
+<para>
+
+</para>
+
+@pspec: 
+@string: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_pattern_match_simple ##### -->
+<para>
+
+</para>
+
+@pattern: 
+@string: 
+@Returns: 
+
+

docs/reference/glib/tmpl/queue.sgml

@@ -2,12 +2,32 @@
 Double-ended Queues
 
 <!-- ##### SECTION Short_Description ##### -->
-
+double-ended queue data structure
-Double-ended queue data structure
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+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.  
+</para>
+<para>
+The data contained in each element can be either integer values, by using one
+of the
+<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
+or simply pointers to any type of data.
+</para>
+<para>
+To create a new #GQueue, use g_queue_new().
+</para>
+<para>
+To add elements, use g_queue_push_head(), g_queue_push_head_link(), 
+g_queue_push_tail() and g_queue_push_tail_link().
+</para>
+<para>
+To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
+</para>
+<para>
+To free the entire queue, use g_queue_free().
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -17,12 +37,12 @@ Double-ended queue data structure
 
 <!-- ##### STRUCT GQueue ##### -->
 <para>
-
+Contains the public fields of a <link linkend="glib-queues">Queue</link>.
 </para>
 
-@head: 
+@head: a pointer to the first element of the queue.
-@tail: 
+@tail: a pointer to the last element of the queue.
-@length: 
+@length: the number of elements in the queue.
 
 <!-- ##### FUNCTION g_queue_new ##### -->
 <para>

docs/reference/glib/tmpl/threads.sgml

@@ -191,10 +191,9 @@ elements of @vtable are non-%NULL, then g_thread_init() will abort.
 <note>
 <para>
 To use g_thread_init() in your program, you have to link with the
-libraries, that the command "glib-config --libs gthread" outputs. This
+libraries that the command <command>pkg-config --libs gthread-2.0</command> 
-is not the case for all the other thread related functions of
+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
+GLib. Those can be used without having to link with the thread libraries.
-libraries.
 </para>
 </note>
 

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 <literal>errno</literal> error number, e.g. %EINVAL.
  *
- * Return value: A #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL
+ * Converts an <literal>errno</literal> 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
+ * @channel: a #GIOChannel.
- * @flags: the flags to set on the channel
+ * @flags: the flags to set on the channel.
- * @error: A location to return an error of type #GIOChannelError
+ * @error: A location to return an error of type #GIOChannelError.
  *
- * Return value:
+ * Sets flags on the channel.
+ *
+ * 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
+ * Returns whether the channel will be closed on the final unref of the 
- *               the GIOChannel data structure. The default value of
+ * #GIOChannel data structure. The default value of this is %TRUE for 
- *               this is %TRUE for channels created by g_io_channel_new_file (),
+ * channels created by g_io_channel_new_file(), and %FALSE for all other 
- *               and %FALSE for all other channels.
+ * 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.
  *
- * Return Value: the buffering state of the channel
+ * Returns 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,

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, <emphasis>not</emphasis> 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, <emphasis>not</emphasis> 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)
 {

glib/gstrfuncs.c

@@ -144,8 +144,8 @@ g_strnfill (gsize length,
 
 /**
  * g_stpcpy:
- * @dest: destination buffer
+ * @dest: destination buffer.
- * @src: source string
+ * @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
+ *               semantics that exactly match g_ascii_tolower(). (Note
- *               that this is unlike the old g_strdown, which modified
+ *               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
+ *               semantics that exactly match g_ascii_toupper(). (Note
- *               that this is unlike the old g_strup, which modified
+ *               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
+ * @s1: string to compare with @s2.
- * @s2: string to compare with @s1
+ * @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
+ * @s1: string to compare with @s2.
- * @s2: string to compare with @s1
+ * @s2: string to compare with @s1.
- * @n:  number of characters to compare
+ * @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()
+ * Return value: a newly-allocated %NULL-terminated array of strings. Use 
- *    to free it.
+ *    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: a string.
- * @haystack_len: The maximum length of haystack
+ * @haystack_len: the maximum length of @haystack.
- * @needle: The string to search for.
+ * @needle: the string to search for.
  *
- * Searches the string haystack for the first occurrence
+ * Searches the string @haystack for the first occurrence
- * of the string needle, limiting the length of the search
+ * of the string @needle, limiting the length of the search
- * to haystack_len. 
+ * to @haystack_len. 
  *
- * Return value: A pointer to the found occurrence, or
+ * Return value: a pointer to the found occurrence, or
- * NULL if not found.
+ *    %NULL if not found.
  **/
 gchar *
 g_strstr_len (const gchar *haystack,
@@ -1850,15 +1850,15 @@ g_strstr_len (const gchar *haystack,
 }
 
 /**
- * g_strrstr_len:
+ * g_strrstr:
- * @haystack: a nul-terminated string
+ * @haystack: a nul-terminated string.
- * @needle: The nul-terminated string to search for.
+ * @needle: the nul-terminated string to search for.
  *
- * Searches the string haystack for the last occurrence
+ * Searches the string @haystack for the last occurrence
- * of the string needle.
+ * of the string @needle.
  *
- * Return value: A pointer to the found occurrence, or
+ * Return value: a pointer to the found occurrence, or
- * NULL if not found.
+ *    %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: a nul-terminated string.
- * @haystack_len: The maximum length of haystack
+ * @haystack_len: the maximum length of @haystack.
- * @needle: The nul-terminated string to search for.
+ * @needle: the nul-terminated string to search for.
  *
- * Searches the string haystack for the last occurrence
+ * Searches the string @haystack for the last occurrence
- * of the string needle, limiting the length of the search
+ * of the string @needle, limiting the length of the search
- * to haystack_len. 
+ * to @haystack_len. 
  *
- * Return value: A pointer to the found occurrence, or
+ * Return value: a pointer to the found occurrence, or
- * NULL if not found.
+ *    %NULL if not found.
  **/
 gchar *
 g_strrstr_len (const gchar *haystack,