Docs: don't use the type tag

Just avoid explicit docbook markup.

8 files changed, 203 insertions, 226 deletions

diff --git a/gio/gcredentials.c b/gio/gcredentials.c
index 8e9f28a02..dddf014eb 100644
--- a/gio/gcredentials.c
+++ b/gio/gcredentials.c
@@ -53,21 +53,19 @@
  * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
  * g_unix_connection_receive_credentials() for details.
  *
- * On Linux, the native credential type is a <type>struct ucred</type>
- * - see the
- * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- * man page for details. This corresponds to
+ * On Linux, the native credential type is a struct ucred - see the
+ * unix(7) man page for details. This corresponds to
  * %G_CREDENTIALS_TYPE_LINUX_UCRED.
  *
  * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
- * credential type is a <type>struct cmsgcred</type>. This corresponds
+ * credential type is a struct cmsgcred. This corresponds
  * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
  *
- * On OpenBSD, the native credential type is a <type>struct sockpeercred</type>.
+ * On OpenBSD, the native credential type is a struct sockpeercred.
  * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
  *
  * On Solaris (including OpenSolaris and its derivatives), the native
- * credential type is a <type>ucred_t</type>. This corresponds to
+ * credential type is a ucred_t. This corresponds to
  * %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
  */
 
diff --git a/gio/ginetsocketaddress.c b/gio/ginetsocketaddress.c
index 87b0d494e..9d0f1cd33 100644
--- a/gio/ginetsocketaddress.c
+++ b/gio/ginetsocketaddress.c
@@ -44,8 +44,8 @@
 /**
  * GInetSocketAddress:
  *
- * An IPv4 or IPv6 socket address, corresponding to a <type>struct
- * sockaddr_in</type> or <type>struct sockaddr_in6</type>.
+ * An IPv4 or IPv6 socket address, corresponding to a struct
+ * sockaddr_in or struct sockaddr_in6.
  */
 
 struct _GInetSocketAddressPrivate
diff --git a/gio/gsocketaddress.c b/gio/gsocketaddress.c
index 844035f8a..c1298b37a 100644
--- a/gio/gsocketaddress.c
+++ b/gio/gsocketaddress.c
@@ -47,16 +47,15 @@
  *     for socket communication
  * @include: gio/gio.h
  *
- * #GSocketAddress is the equivalent of <type>struct sockaddr</type>
- * in the BSD sockets API. This is an abstract class; use
- * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress
- * for UNIX domain sockets.
+ * #GSocketAddress is the equivalent of struct sockaddr in the BSD
+ * sockets API. This is an abstract class; use #GInetSocketAddress
+ * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets.
  */
 
 /**
  * GSocketAddress:
  *
- * A socket endpoint address, corresponding to <type>struct sockaddr</type>
+ * A socket endpoint address, corresponding to struct sockaddr
  * or one of its subtypes.
  */
 
@@ -80,7 +79,7 @@ G_DEFINE_ABSTRACT_TYPE_WITH_CODE (GSocketAddress, g_socket_address, G_TYPE_OBJEC
  *
  * Gets the socket family type of @address.
  *
- * Returns: the socket family type of @address.
+ * Returns: the socket family type of @address
  *
  * Since: 2.22
  */
@@ -143,11 +142,11 @@ g_socket_address_init (GSocketAddress *address)
  * g_socket_address_get_native_size:
  * @address: a #GSocketAddress
  *
- * Gets the size of @address's native <type>struct sockaddr</type>.
+ * Gets the size of @address's native struct sockaddr.
  * You can use this to allocate memory to pass to
  * g_socket_address_to_native().
  *
- * Returns: the size of the native <type>struct sockaddr</type> that
+ * Returns: the size of the native struct sockaddr that
  *     @address represents
  *
  * Since: 2.22
@@ -164,17 +163,16 @@ g_socket_address_get_native_size (GSocketAddress *address)
  * g_socket_address_to_native:
  * @address: a #GSocketAddress
  * @dest: a pointer to a memory location that will contain the native
- * <type>struct sockaddr</type>.
+ * struct sockaddr
  * @destlen: the size of @dest. Must be at least as large as
- * g_socket_address_get_native_size().
- * @error: #GError for error reporting, or %NULL to ignore.
+ *     g_socket_address_get_native_size()
+ * @error: #GError for error reporting, or %NULL to ignore
  *
- * Converts a #GSocketAddress to a native <type>struct
- * sockaddr</type>, which can be passed to low-level functions like
- * connect() or bind().
+ * Converts a #GSocketAddress to a native struct sockaddr, which can
+ * be passed to low-level functions like connect() or bind().
  *
- * If not enough space is available, a %G_IO_ERROR_NO_SPACE error is
- * returned. If the address type is not known on the system
+ * If not enough space is available, a %G_IO_ERROR_NO_SPACE error
+ * is returned. If the address type is not known on the system
  * then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
  *
  * Returns: %TRUE if @dest was filled in, %FALSE on error
@@ -194,14 +192,14 @@ g_socket_address_to_native (GSocketAddress  *address,
 
 /**
  * g_socket_address_new_from_native:
- * @native: a pointer to a <type>struct sockaddr</type>
+ * @native: a pointer to a struct sockaddr
  * @len: the size of the memory location pointed to by @native
  *
  * Creates a #GSocketAddress subclass corresponding to the native
- * <type>struct sockaddr</type> @native.
+ * struct sockaddr @native.
  *
- * Returns: a new #GSocketAddress if @native could successfully be converted,
- * otherwise %NULL.
+ * Returns: a new #GSocketAddress if @native could successfully
+ *     be converted, otherwise %NULL
  *
  * Since: 2.22
  */
diff --git a/gio/gunixsocketaddress.c b/gio/gunixsocketaddress.c
index 41e751c4d..96974bbcb 100644
--- a/gio/gunixsocketaddress.c
+++ b/gio/gunixsocketaddress.c
@@ -55,7 +55,7 @@
  * GUnixSocketAddress:
  *
  * A UNIX-domain (local) socket address, corresponding to a
- * <type>struct sockaddr_un</type>.
+ * struct sockaddr_un.
  */
 
 enum
diff --git a/glib/docs.c b/glib/docs.c
index 6ca8c480f..f74f783cf 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -64,8 +64,7 @@
  * gpointer:
  *
  * An untyped pointer.
- * #gpointer looks better and is easier to use
- * than <type>void*</type>.
+ * #gpointer looks better and is easier to use than void*.
  */
 
 /**
@@ -81,19 +80,19 @@
 /**
  * gchar:
  *
- * Corresponds to the standard C <type>char</type> type.
+ * Corresponds to the standard C char type.
  */
 
 /**
  * guchar:
  *
- * Corresponds to the standard C <type>unsigned char</type> type.
+ * Corresponds to the standard C unsigned char type.
  */
 
 /**
  * gint:
  *
- * Corresponds to the standard C <type>int</type> type.
+ * Corresponds to the standard C int type.
  * Values of this type can range from #G_MININT to #G_MAXINT.
  */
 
@@ -112,7 +111,7 @@
 /**
  * guint:
  *
- * Corresponds to the standard C <type>unsigned int</type> type.
+ * Corresponds to the standard C unsigned int type.
  * Values of this type can range from 0 to #G_MAXUINT.
  */
 
@@ -125,7 +124,7 @@
 /**
  * gshort:
  *
- * Corresponds to the standard C <type>short</type> type.
+ * Corresponds to the standard C short type.
  * Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
  */
 
@@ -144,7 +143,7 @@
 /**
  * gushort:
  *
- * Corresponds to the standard C <type>unsigned short</type> type.
+ * Corresponds to the standard C unsigned short type.
  * Values of this type can range from 0 to #G_MAXUSHORT.
  */
 
@@ -157,7 +156,7 @@
 /**
  * glong:
  *
- * Corresponds to the standard C <type>long</type> type.
+ * Corresponds to the standard C long type.
  * Values of this type can range from #G_MINLONG to #G_MAXLONG.
  */
 
@@ -176,7 +175,7 @@
 /**
  * gulong:
  *
- * Corresponds to the standard C <type>unsigned long</type> type.
+ * Corresponds to the standard C unsigned long type.
  * Values of this type can range from 0 to #G_MAXULONG.
  */
 
@@ -491,7 +490,7 @@
 /**
  * gfloat:
  *
- * Corresponds to the standard C <type>float</type> type.
+ * Corresponds to the standard C float type.
  * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
  */
 
@@ -513,7 +512,7 @@
 /**
  * gdouble:
  *
- * Corresponds to the standard C <type>double</type> type.
+ * Corresponds to the standard C double type.
  * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
  */
 
@@ -536,7 +535,7 @@
  * gsize:
  *
  * An unsigned integer type of the result of the sizeof operator,
- * corresponding to the <type>size_t</type> type defined in C99.
+ * corresponding to the size_t type defined in C99.
  * This type is wide enough to hold the numeric value of a pointer,
  * so it is usually 32bit wide on a 32bit platform and 64bit wide
  * on a 64bit platform. Values of this type can range from 0 to
@@ -577,7 +576,7 @@
  * gssize:
  *
  * A signed variant of #gsize, corresponding to the
- * <type>ssize_t</type> defined on most platforms.
+ * ssize_t defined on most platforms.
  * Values of this type can range from #G_MINSSIZE
  * to #G_MAXSSIZE.
  *
@@ -614,7 +613,7 @@
  * goffset:
  *
  * A signed integer type that is used for file offsets,
- * corresponding to the C99 type <type>off64_t</type>.
+ * corresponding to the C99 type off64_t.
  * Values of this type can range from #G_MINOFFSET to
  * #G_MAXOFFSET.
  *
@@ -670,7 +669,7 @@
 /**
  * gintptr:
  *
- * Corresponds to the C99 type <type>intptr_t</type>,
+ * Corresponds to the C99 type intptr_t,
  * a signed integer type that can hold any pointer.
  *
  * To print or scan values of this type, use
@@ -701,7 +700,7 @@
 /**
  * guintptr:
  *
- * Corresponds to the C99 type <type>uintptr_t</type>,
+ * Corresponds to the C99 type uintptr_t,
  * an unsigned integer type that can hold any pointer.
  *
  * To print or scan values of this type, use
@@ -1772,15 +1771,14 @@
 
 /**
  * G_VA_COPY:
- * @ap1: the <type>va_list</type> variable to place a copy of @ap2 in
- * @ap2: a <type>va_list</type>
+ * @ap1: the va_list variable to place a copy of @ap2 in
+ * @ap2: a va_list
  *
- * Portable way to copy <type>va_list</type> variables.
+ * Portable way to copy va_list variables.
  *
- * In order to use this function, you must include
- * <filename>string.h</filename> yourself, because this macro may
- * use memmove() and GLib does not include <filename>string.h</filename>
- * for you.
+ * In order to use this function, you must include string.h yourself,
+ * because this macro may use memmove() and GLib does not include
+ * string.h for you.
  */
 
 /**
diff --git a/glib/gdate.c b/glib/gdate.c
index 397ec6b1f..46c933232 100644
--- a/glib/gdate.c
+++ b/glib/gdate.c
@@ -1281,7 +1281,7 @@ g_date_set_parse (GDate       *d,
 /**
  * g_date_set_time_t:
  * @date: a #GDate 
- * @timet: <type>time_t</type> value to set
+ * @timet: time_t value to set
  *
  * Sets the value of a date to the date corresponding to a time 
  * specified as a time_t. The time to date conversion is done using 
diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index 07a24c098..bf8fa184e 100644
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -99,9 +99,9 @@
  * Unlike the standard C library isalnum() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII alphanumeric character
  */
@@ -115,9 +115,9 @@
  * Unlike the standard C library isalpha() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII alphabetic character
  */
@@ -131,9 +131,9 @@
  * Unlike the standard C library iscntrl() function, this only
  * recognizes standard ASCII control characters and ignores the
  * locale, returning %FALSE for all non-ASCII characters. Also,
- * unlike the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * unlike the standard library function, this takes a char, not
+ * an int, so don't call it on %EOF, but no need to cast to #guchar
+ * before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII control character.
  */
@@ -145,9 +145,8 @@
  * Determines whether a character is digit (0-9).
  *
  * Unlike the standard C library isdigit() function, this takes
- * a <type>char</type>, not an <type>int</type>, so don't call it
- * on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly
- * non-ASCII character in.
+ * a char, not an int, so don't call it  on %EOF, but no need to
+ * cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII digit.
  */
@@ -161,9 +160,9 @@
  * Unlike the standard C library isgraph() function, this only
  * recognizes standard ASCII characters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
- * to cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII printing character other than space.
  */
@@ -177,10 +176,9 @@
  * Unlike the standard C library islower() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
- * to worry about casting to #guchar before passing a possibly
- * non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to worry about casting
+ * to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII lower case letter
  */
@@ -194,9 +192,9 @@
  * Unlike the standard C library isprint() function, this only
  * recognizes standard ASCII characters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
- * to cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII printing character.
  */
@@ -210,9 +208,9 @@
  * Unlike the standard C library ispunct() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII punctuation character.
  */
@@ -226,9 +224,9 @@
  * Unlike the standard C library isspace() function, this only
  * recognizes standard ASCII white-space and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII white-space character
  */
@@ -242,10 +240,9 @@
  * Unlike the standard C library isupper() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * worry about casting to #guchar before passing a possibly non-ASCII
- * character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to worry about casting
+ * to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII upper case letter
  */
@@ -257,9 +254,8 @@
  * Determines whether a character is a hexadecimal-digit character.
  *
  * Unlike the standard C library isxdigit() function, this takes
- * a <type>char</type>, not an <type>int</type>, so don't call it
- * on <literal>EOF</literal>, but no need to cast to #guchar before passing a
- * possibly non-ASCII character in.
+ * a char, not an int, so don't call it on %EOF, but no need to
+ * cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
  */
diff --git a/glib/gutf8.c b/glib/gutf8.c
index 1f6e3593a..c0ac8cb17 100644
--- a/glib/gutf8.c
+++ b/glib/gutf8.c
@@ -139,7 +139,7 @@ const gchar * const g_utf8_skip = utf8_skip_data;
  * it starts with an appropriate byte.
  *
  * Return value: a pointer to the found character or %NULL.
- **/
+ */
 gchar *
 g_utf8_find_prev_char (const char *str,
 		       const char *p)
@@ -156,7 +156,7 @@ g_utf8_find_prev_char (const char *str,
  * g_utf8_find_next_char:
  * @p: a pointer to a position within a UTF-8 encoded string
  * @end: a pointer to the byte following the end of the string,
- * or %NULL to indicate that the string is nul-terminated.
+ *     or %NULL to indicate that the string is nul-terminated
  *
  * Finds the start of the next UTF-8 character in the string after @p.
  *
@@ -165,7 +165,7 @@ g_utf8_find_prev_char (const char *str,
  * it starts with an appropriate byte.
  * 
  * Return value: a pointer to the found character or %NULL
- **/
+ */
 gchar *
 g_utf8_find_next_char (const gchar *p,
 		       const gchar *end)
@@ -193,8 +193,8 @@ g_utf8_find_next_char (const gchar *p,
  * it starts with an appropriate byte. If @p might be the first
  * character of the string, you must use g_utf8_find_prev_char() instead.
  * 
- * Return value: a pointer to the found character.
- **/
+ * Return value: a pointer to the found character
+ */
 gchar *
 g_utf8_prev_char (const gchar *p)
 {
@@ -205,7 +205,7 @@ g_utf8_prev_char (const gchar *p)
 	return (gchar *)p;
     }
 }
-
+ 
 /**
  * g_utf8_strlen:
  * @p: pointer to the start of a UTF-8 encoded string
@@ -220,7 +220,7 @@ g_utf8_prev_char (const gchar *p)
  * middle of a character, the last (partial) character is not counted.
  *
  * Return value: the length of the string in characters
- **/
+ */
 glong
 g_utf8_strlen (const gchar *p,
                gssize       max)
@@ -267,8 +267,7 @@ g_utf8_strlen (const gchar *p,
  * @end_pos: another character offset within @str
  *
  * Copies a substring out of a UTF-8 encoded string.
- * The substring will contain @end_pos - @start_pos
- * characters.
+ * The substring will contain @end_pos - @start_pos characters.
  *
  * Returns: a newly allocated copy of the requested
  *     substring. Free with g_free() when no longer needed.
@@ -297,13 +296,14 @@ g_utf8_substring (const gchar *str,
  * @p: a pointer to Unicode character encoded as UTF-8
  * 
  * Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
- * If @p does not point to a valid UTF-8 encoded character, results are
- * undefined. If you are not sure that the bytes are complete
+ *
+ * If @p does not point to a valid UTF-8 encoded character, results
+ * are undefined. If you are not sure that the bytes are complete
  * valid Unicode characters, you should use g_utf8_get_char_validated()
  * instead.
  * 
  * Return value: the resulting character
- **/
+ */
 gunichar
 g_utf8_get_char (const gchar *p)
 {
@@ -332,17 +332,14 @@ g_utf8_get_char (const gchar *p)
  * instead of forwards if @offset is in the last fourth of the string,
  * since moving forward is about 3 times faster than moving backward.
  *
- * <note><para>
- * This function doesn't abort when reaching the end of @str. Therefore
- * you should be sure that @offset is within string boundaries before
- * calling that function. Call g_utf8_strlen() when unsure.
- *
+ * Note that this function doesn't abort when reaching the end of @str.
+ * Therefore you should be sure that @offset is within string boundaries
+ * before calling that function. Call g_utf8_strlen() when unsure.
  * This limitation exists as this function is called frequently during
  * text rendering and therefore has to be as fast as possible.
- * </para></note>
  *
  * Return value: the resulting pointer
- **/
+ */
 gchar *
 g_utf8_offset_to_pointer  (const gchar *str,
 			   glong        offset)
@@ -386,7 +383,7 @@ g_utf8_offset_to_pointer  (const gchar *str,
  * a negative offset in this case.
  * 
  * Return value: the resulting character offset
- **/
+ */
 glong    
 g_utf8_pointer_to_offset (const gchar *str,
 			  const gchar *pos)
@@ -413,14 +410,13 @@ g_utf8_pointer_to_offset (const gchar *str,
  * @src: UTF-8 encoded string
  * @n: character count
  * 
- * Like the standard C strncpy() function, but 
- * copies a given number of characters instead of a given number of 
- * bytes. The @src string must be valid UTF-8 encoded text. 
- * (Use g_utf8_validate() on all text before trying to use UTF-8 
- * utility functions with it.)
+ * Like the standard C strncpy() function, but copies a given number
+ * of characters instead of a given number of bytes. The @src string
+ * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
+ * text before trying to use UTF-8 utility functions with it.)
  * 
  * Return value: @dest
- **/
+ */
 gchar *
 g_utf8_strncpy (gchar       *dest,
 		const gchar *src,
@@ -449,7 +445,7 @@ g_utf8_strncpy (gchar       *dest,
  * Converts a single character to UTF-8.
  * 
  * Return value: number of bytes written
- **/
+ */
 int
 g_unichar_to_utf8 (gunichar c,
 		   gchar   *outbuf)
@@ -514,9 +510,9 @@ g_unichar_to_utf8 (gunichar c,
  * If @len is -1, allow unbounded search.
  * 
  * Return value: %NULL if the string does not contain the character, 
- *   otherwise, a pointer to the start of the leftmost occurrence of 
- *   the character in the string.
- **/
+ *     otherwise, a pointer to the start of the leftmost occurrence
+ *     of the character in the string.
+ */
 gchar *
 g_utf8_strchr (const char *p,
 	       gssize      len,
@@ -542,9 +538,9 @@ g_utf8_strchr (const char *p,
  * If @len is -1, allow unbounded search.
  * 
  * Return value: %NULL if the string does not contain the character, 
- *   otherwise, a pointer to the start of the rightmost occurrence of the 
- *   character in the string.
- **/
+ *     otherwise, a pointer to the start of the rightmost occurrence
+ *     of the character in the string.
+ */
 gchar *
 g_utf8_strrchr (const char *p,
 		gssize      len,
@@ -651,7 +647,7 @@ g_utf8_get_char_extended (const  gchar *p,
  * g_utf8_get_char_validated:
  * @p: a pointer to Unicode character encoded as UTF-8
  * @max_len: the maximum number of bytes to read, or -1, for no maximum or
- *           if @p is nul-terminated
+ *     if @p is nul-terminated
  * 
  * Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
  * This function checks for incomplete characters, for invalid characters
@@ -659,14 +655,14 @@ g_utf8_get_char_extended (const  gchar *p,
  * overlong encodings of valid characters.
  * 
  * Return value: the resulting character. If @p points to a partial
- *    sequence at the end of a string that could begin a valid 
- *    character (or if @max_len is zero), returns (gunichar)-2; 
- *    otherwise, if @p does not point to a valid UTF-8 encoded 
- *    Unicode character, returns (gunichar)-1.
- **/
+ *     sequence at the end of a string that could begin a valid 
+ *     character (or if @max_len is zero), returns (gunichar)-2; 
+ *     otherwise, if @p does not point to a valid UTF-8 encoded 
+ *     Unicode character, returns (gunichar)-1.
+ */
 gunichar
-g_utf8_get_char_validated (const  gchar *p,
-			   gssize max_len)
+g_utf8_get_char_validated (const gchar *p,
+			   gssize       max_len)
 {
   gunichar result;
 
@@ -687,9 +683,9 @@ g_utf8_get_char_validated (const  gchar *p,
  * g_utf8_to_ucs4_fast:
  * @str: a UTF-8 encoded string
  * @len: the maximum length of @str to use, in bytes. If @len < 0,
- *       then the string is nul-terminated.
- * @items_written: (allow-none): location to store the number of characters in the
- *                 result, or %NULL.
+ *     then the string is nul-terminated.
+ * @items_written: (allow-none): location to store the number of
+ *     characters in the result, or %NULL.
  *
  * Convert a string from UTF-8 to a 32-bit fixed width
  * representation as UCS-4, assuming valid UTF-8 input.
@@ -698,8 +694,8 @@ g_utf8_get_char_validated (const  gchar *p,
  * will be added to the string after the converted text.
  * 
  * Return value: a pointer to a newly allocated UCS-4 string.
- *               This value must be freed with g_free().
- **/
+ *     This value must be freed with g_free().
+ */
 gunichar *
 g_utf8_to_ucs4_fast (const gchar *str,
 		     glong        len,              
@@ -750,7 +746,8 @@ g_utf8_to_ucs4_fast (const gchar *str,
 	      /* It's an out-of-sequence 10xxxxxxx byte.
 	       * Rather than making an ugly hash of this and the next byte
 	       * and overrunning the buffer, it's more useful to treat it
-	       * with a replacement character */
+	       * with a replacement character
+	       */
 	      result[i] = 0xfffd;
 	      continue;
 	    }
@@ -790,28 +787,27 @@ try_malloc_n (gsize n_blocks, gsize n_block_bytes, GError **error)
  * g_utf8_to_ucs4:
  * @str: a UTF-8 encoded string
  * @len: the maximum length of @str to use, in bytes. If @len < 0,
- *       then the string is nul-terminated.
+ *     then the string is nul-terminated.
  * @items_read: (allow-none): location to store number of bytes read, or %NULL.
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
- *              character. If an error occurs then the index of the
- *              invalid input is stored here.
- * @items_written: (allow-none): location to store number of characters written or %NULL.
- *                 The value here stored does not include the trailing 0
- *                 character. 
+ *     If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     returned in case @str contains a trailing partial
+ *     character. If an error occurs then the index of the
+ *     invalid input is stored here.
+ * @items_written: (allow-none): location to store number of characters
+ *     written or %NULL. The value here stored does not include the
+ *     trailing 0 character. 
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UTF-8 to a 32-bit fixed width
  * representation as UCS-4. A trailing 0 character will be added to the
  * string after the converted text.
  * 
  * Return value: a pointer to a newly allocated UCS-4 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
- **/
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
+ */
 gunichar *
 g_utf8_to_ucs4 (const gchar *str,
 		glong        len,             
@@ -876,11 +872,12 @@ g_utf8_to_ucs4 (const gchar *str,
  * g_ucs4_to_utf8:
  * @str: a UCS-4 encoded string
  * @len: the maximum length (number of characters) of @str to use. 
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of characters read, or %NULL.
- * @items_written: (allow-none): location to store number of bytes written or %NULL.
- *                 The value here stored does not include the trailing 0
- *                 byte. 
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of characters
+ *     read, or %NULL.
+ * @items_written: (allow-none): location to store number of bytes
+ *     written or %NULL. The value here stored does not include the
+ *     trailing 0 byte. 
  * @error: location to store the error occurring, or %NULL to ignore
  *         errors. Any of the errors in #GConvertError other than
  *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
@@ -889,12 +886,10 @@ g_utf8_to_ucs4 (const gchar *str,
  * to UTF-8. The result will be terminated with a 0 byte.
  * 
  * Return value: a pointer to a newly allocated UTF-8 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set. In that case, @items_read will be
- *               set to the position of the first invalid input 
- *               character.
- **/
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set. In that case, @items_read
+ *     will be set to the position of the first invalid input character.
+ */
 gchar *
 g_ucs4_to_utf8 (const gunichar *str,
 		glong           len,              
@@ -950,19 +945,17 @@ g_ucs4_to_utf8 (const gunichar *str,
 /**
  * g_utf16_to_utf8:
  * @str: a UTF-16 encoded string
- * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. 
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of words read, or %NULL.
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
- *              character. If an error occurs then the index of the
- *              invalid input is stored here.
- * @items_written: (allow-none): location to store number of bytes written, or %NULL.
- *                 The value stored here does not include the trailing
- *                 0 byte.
+ * @len: the maximum length (number of #gunichar2) of @str to use. 
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of words read,
+ *     or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     returned in case @str contains a trailing partial character. If
+ *     an error occurs then the index of the invalid input is stored here.
+ * @items_written: (allow-none): location to store number of bytes written,
+ *     or %NULL. The value stored here does not include the trailing 0 byte.
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UTF-16 to UTF-8. The result will be
  * terminated with a 0 byte.
@@ -979,9 +972,8 @@ g_ucs4_to_utf8 (const gunichar *str,
  * things unpaired surrogates.
  *
  * Return value: a pointer to a newly allocated UTF-8 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
  **/
 gchar *
 g_utf16_to_utf8 (const gunichar2  *str,
@@ -990,8 +982,8 @@ g_utf16_to_utf8 (const gunichar2  *str,
 		 glong            *items_written,
 		 GError          **error)
 {
-  /* This function and g_utf16_to_ucs4 are almost exactly identical - The lines that differ
-   * are marked.
+  /* This function and g_utf16_to_ucs4 are almost exactly identical -
+   * The lines that differ are marked.
    */
   const gunichar2 *in;
   gchar *out;
@@ -1107,28 +1099,26 @@ g_utf16_to_utf8 (const gunichar2  *str,
 /**
  * g_utf16_to_ucs4:
  * @str: a UTF-16 encoded string
- * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. 
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of words read, or %NULL.
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
- *              character. If an error occurs then the index of the
- *              invalid input is stored here.
- * @items_written: (allow-none): location to store number of characters written, or %NULL.
- *                 The value stored here does not include the trailing
- *                 0 character.
+ * @len: the maximum length (number of #gunichar2) of @str to use. 
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of words read,
+ *     or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     returned in case @str contains a trailing partial character. If
+ *     an error occurs then the index of the invalid input is stored here.
+ * @items_written: (allow-none): location to store number of characters
+ *     written, or %NULL. The value stored here does not include the trailing
+ *     0 character.
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UTF-16 to UCS-4. The result will be
  * nul-terminated.
  * 
  * Return value: a pointer to a newly allocated UCS-4 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
- **/
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
+ */
 gunichar *
 g_utf16_to_ucs4 (const gunichar2  *str,
 		 glong             len,              
@@ -1248,27 +1238,25 @@ g_utf16_to_ucs4 (const gunichar2  *str,
  * g_utf8_to_utf16:
  * @str: a UTF-8 encoded string
  * @len: the maximum length (number of bytes) of @str to use.
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of bytes read, or %NULL.
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
- *              character. If an error occurs then the index of the
- *              invalid input is stored here.
- * @items_written: (allow-none): location to store number of <type>gunichar2</type> written,
- *                 or %NULL.
- *                 The value stored here does not include the trailing 0.
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of bytes read,
+ *     or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     returned in case @str contains a trailing partial character. If
+ *     an error occurs then the index of the invalid input is stored here.
+ * @items_written: (allow-none): location to store number of #gunichar2
+ *     written, or %NULL. The value stored here does not include the
+ *     trailing 0.
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UTF-8 to UTF-16. A 0 character will be
  * added to the result after the converted text.
  *
  * Return value: a pointer to a newly allocated UTF-16 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
- **/
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
+ */
 gunichar2 *
 g_utf8_to_utf16 (const gchar *str,
 		 glong        len,
@@ -1367,25 +1355,24 @@ g_utf8_to_utf16 (const gchar *str,
  * g_ucs4_to_utf16:
  * @str: a UCS-4 encoded string
  * @len: the maximum length (number of characters) of @str to use. 
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of bytes read, or %NULL.
- *              If an error occurs then the index of the invalid input
- *              is stored here.
- * @items_written: (allow-none): location to store number of <type>gunichar2</type> 
- *                 written, or %NULL. The value stored here does not 
- *                 include the trailing 0.
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of bytes read,
+ *     or %NULL. If an error occurs then the index of the invalid input
+ *     is stored here.
+ * @items_written: (allow-none): location to store number of #gunichar2 
+ *     written, or %NULL. The value stored here does not include the
+ *     trailing 0.
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UCS-4 to UTF-16. A 0 character will be
  * added to the result after the converted text.
  * 
  * Return value: a pointer to a newly allocated UTF-16 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
- **/
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
+ */
 gunichar2 *
 g_ucs4_to_utf16 (const gunichar  *str,
 		 glong            len,              
@@ -1631,7 +1618,7 @@ fast_validate_len (const char *str,
  * with g_utf8_validate() before doing anything else with it.
  * 
  * Return value: %TRUE if the text was valid UTF-8
- **/
+ */
 gboolean
 g_utf8_validate (const char   *str,
 		 gssize        max_len,    
@@ -1675,7 +1662,7 @@ g_unichar_validate (gunichar ch)
  * g_utf8_strreverse:
  * @str: a UTF-8 encoded string
  * @len: the maximum length of @str to use, in bytes. If @len < 0,
- *       then the string is nul-terminated.
+ *     then the string is nul-terminated.
  *
  * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. 
  * (Use g_utf8_validate() on all text before trying to use UTF-8 
@@ -1691,7 +1678,7 @@ g_unichar_validate (gunichar ch)
  * newly-allocated memory, which should be freed with g_free() when
  * no longer needed. 
  *
- * Returns: a newly-allocated string which is the reverse of @str.
+ * Returns: a newly-allocated string which is the reverse of @str
  *
  * Since: 2.2
  */