Minor markup fixes.

        * 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.

        * glib/tmpl/caches.sgml: GCs are cached by GTK, not by GDK.

19 files changed, 302 insertions, 242 deletions

diff --git a/ChangeLog b/ChangeLog
index 80fbeb378..ab77fe008 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -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