Docs: don't use the type tag

Just avoid explicit docbook markup.

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>
+ * On Linux, the native credential type is a struct ucred - see the
- * - see the
+ * unix(7) man page for details. This corresponds to
- * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- * 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.
  */
 

gio/ginetsocketaddress.c

@@ -44,8 +44,8 @@
 /**
  * GInetSocketAddress:
  *
- * An IPv4 or IPv6 socket address, corresponding to a <type>struct
+ * An IPv4 or IPv6 socket address, corresponding to a struct
- * sockaddr_in</type> or <type>struct sockaddr_in6</type>.
+ * sockaddr_in or struct sockaddr_in6.
  */
 
 struct _GInetSocketAddressPrivate

gio/gsocketaddress.c

@@ -47,16 +47,15 @@
  *     for socket communication
  * @include: gio/gio.h
  *
- * #GSocketAddress is the equivalent of <type>struct sockaddr</type>
+ * #GSocketAddress is the equivalent of struct sockaddr in the BSD
- * in the BSD sockets API. This is an abstract class; use
+ * sockets API. This is an abstract class; use #GInetSocketAddress
- * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress
+ * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets.
- * 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().
+ *     g_socket_address_get_native_size()
- * @error: #GError for error reporting, or %NULL to ignore.
+ * @error: #GError for error reporting, or %NULL to ignore
  *
- * Converts a #GSocketAddress to a native <type>struct
+ * Converts a #GSocketAddress to a native struct sockaddr, which can
- * sockaddr</type>, which can be passed to low-level functions like
+ * be passed to low-level functions like connect() or bind().
- * connect() or bind().
  *
- * If not enough space is available, a %G_IO_ERROR_NO_SPACE error is
+ * If not enough space is available, a %G_IO_ERROR_NO_SPACE error
- * returned. If the address type is not known on the system
+ * 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,
+ * Returns: a new #GSocketAddress if @native could successfully
- * otherwise %NULL.
+ *     be converted, otherwise %NULL
  *
  * Since: 2.22
  */

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

glib/docs.c

@@ -64,8 +64,7 @@
  * gpointer:
  *
  * An untyped pointer.
- * #gpointer looks better and is easier to use
+ * #gpointer looks better and is easier to use than void*.
- * than <type>void*</type>.
  */
 
 /**
@@ -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
+ * @ap1: the va_list variable to place a copy of @ap2 in
- * @ap2: a <type>va_list</type>
+ * @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
+ * In order to use this function, you must include string.h yourself,
- * <filename>string.h</filename> yourself, because this macro may
+ * because this macro may use memmove() and GLib does not include
- * use memmove() and GLib does not include <filename>string.h</filename>
+ * string.h for you.
- * for you.
  */
 
 /**

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 

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>,
+ * the standard library function, this takes a char, not an int,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
+ * so don't call it on %EOF, but no need to cast to #guchar before
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * 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>,
+ * the standard library function, this takes a char, not an int,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
+ * so don't call it on %EOF, but no need to cast to #guchar before
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * 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>,
+ * unlike the standard library function, this takes a char, not
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
+ * an int, so don't call it on %EOF, but no need to cast to #guchar
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * 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
+ * a char, not an int, so don't call it  on %EOF, but no need to
- * on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly
+ * cast to #guchar before passing a possibly non-ASCII character in.
- * 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>,
+ * the standard library function, this takes a char, not an int,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
+ * so don't call it on %EOF, but no need to cast to #guchar before
- * to cast to #guchar before passing a possibly non-ASCII character in.
+ * 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>,
+ * the standard library function, this takes a char, not an int,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
+ * so don't call it on %EOF, but no need to worry about casting
- * to worry about casting to #guchar before passing a possibly
+ * to #guchar before passing a possibly non-ASCII character in.
- * 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>,
+ * the standard library function, this takes a char, not an int,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
+ * so don't call it on %EOF, but no need to cast to #guchar before
- * to cast to #guchar before passing a possibly non-ASCII character in.
+ * 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>,
+ * the standard library function, this takes a char, not an int,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
+ * so don't call it on %EOF, but no need to cast to #guchar before
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * 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>,
+ * the standard library function, this takes a char, not an int,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
+ * so don't call it on %EOF, but no need to cast to #guchar before
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * 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>,
+ * the standard library function, this takes a char, not an int,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
+ * so don't call it on %EOF, but no need to worry about casting
- * worry about casting to #guchar before passing a possibly non-ASCII
+ * to #guchar before passing a possibly non-ASCII character in.
- * 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
+ * a char, not an int, so don't call it on %EOF, but no need to
- * on <literal>EOF</literal>, but no need to cast to #guchar before passing a
+ * cast to #guchar before passing a possibly non-ASCII character in.
- * possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
  */

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)
 {
@@ -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
+ * The substring will contain @end_pos - @start_pos characters.
- * 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>
+ * Note that this function doesn't abort when reaching the end of @str.
- * This function doesn't abort when reaching the end of @str. Therefore
+ * Therefore you should be sure that @offset is within string boundaries
- * you should be sure that @offset is within string boundaries before
+ * before calling that function. Call g_utf8_strlen() when unsure.
- * 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 
+ * Like the standard C strncpy() function, but copies a given number
- * copies a given number of characters instead of a given number of 
+ * of characters instead of a given number of bytes. The @src string
- * bytes. The @src string must be valid UTF-8 encoded text. 
+ * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
- * (Use g_utf8_validate() on all text before trying to use UTF-8 
+ * text before trying to use UTF-8 utility functions with it.)
- * 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 
+ *     otherwise, a pointer to the start of the leftmost occurrence
- *   the character in the string.
+ *     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 
+ *     otherwise, a pointer to the start of the rightmost occurrence
- *   character in the string.
+ *     of the character in the string.
- **/
+ */
 gchar *
 g_utf8_strrchr (const char *p,
 		gssize      len,
@@ -663,7 +659,7 @@ g_utf8_get_char_extended (const  gchar *p,
  *     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)
@@ -688,8 +684,8 @@ g_utf8_get_char_validated (const  gchar *p,
  * @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
+ * @items_written: (allow-none): location to store the number of
- *                 result, or %NULL.
+ *     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.
@@ -699,7 +695,7 @@ g_utf8_get_char_validated (const  gchar *p,
  * 
  * Return value: a pointer to a newly allocated UCS-4 string.
  *     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;
 	    }
@@ -796,9 +793,9 @@ try_malloc_n (gsize n_blocks, gsize n_block_bytes, GError **error)
  *     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.
+ * @items_written: (allow-none): location to store number of characters
- *                 The value here stored does not include the trailing 0
+ *     written or %NULL. The value here stored does not include the
- *                 character. 
+ *     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.
@@ -808,10 +805,9 @@ try_malloc_n (gsize n_blocks, gsize n_block_bytes, GError **error)
  * 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
+ *     This value must be freed with g_free(). If an error occurs,
- *               error occurs, %NULL will be returned and
+ *     %NULL will be returned and @error set.
- *               @error set.
+ */
- **/
 gunichar *
 g_utf8_to_ucs4 (const gchar *str,
 		glong        len,             
@@ -877,10 +873,11 @@ g_utf8_to_ucs4 (const gchar *str,
  * @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_read: (allow-none): location to store number of characters
- * @items_written: (allow-none): location to store number of bytes written or %NULL.
+ *     read, or %NULL.
- *                 The value here stored does not include the trailing 0
+ * @items_written: (allow-none): location to store number of bytes
- *                 byte. 
+ *     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
+ *     This value must be freed with g_free(). If an error occurs,
- *               error occurs, %NULL will be returned and
+ *     %NULL will be returned and @error set. In that case, @items_read
- *               @error set. In that case, @items_read will be
+ *     will be set to the position of the first invalid input character.
- *               set to the position of the first invalid input 
+ */
- *               character.
- **/
 gchar *
 g_ucs4_to_utf8 (const gunichar *str,
 		glong           len,              
@@ -950,16 +945,14 @@ 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. 
+ * @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.
+ * @items_read: (allow-none): location to store number of words read,
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
+ *     returned in case @str contains a trailing partial character. If
- *              character. If an error occurs then the index of the
+ *     an error occurs then the index of the invalid input is stored here.
- *              invalid input is stored here.
+ * @items_written: (allow-none): location to store number of bytes written,
- * @items_written: (allow-none): location to store number of bytes written, or %NULL.
+ *     or %NULL. The value stored here does not include the trailing 0 byte.
- *                 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.
@@ -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
+ *     This value must be freed with g_free(). If an error occurs,
- *               error occurs, %NULL will be returned and
+ *     %NULL will be returned and @error set.
- *               @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
+  /* This function and g_utf16_to_ucs4 are almost exactly identical -
-   * are marked.
+   * The lines that differ are marked.
    */
   const gunichar2 *in;
   gchar *out;
@@ -1107,15 +1099,14 @@ 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. 
+ * @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.
+ * @items_read: (allow-none): location to store number of words read,
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
+ *     returned in case @str contains a trailing partial character. If
- *              character. If an error occurs then the index of the
+ *     an error occurs then the index of the invalid input is stored here.
- *              invalid input is stored here.
+ * @items_written: (allow-none): location to store number of characters
- * @items_written: (allow-none): location to store number of characters written, or %NULL.
+ *     written, or %NULL. The value stored here does not include the trailing
- *                 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
@@ -1125,10 +1116,9 @@ g_utf16_to_utf8 (const gunichar2  *str,
  * nul-terminated.
  * 
  * Return value: a pointer to a newly allocated UCS-4 string.
- *               This value must be freed with g_free(). If an
+ *     This value must be freed with g_free(). If an error occurs,
- *               error occurs, %NULL will be returned and
+ *     %NULL will be returned and @error set.
- *               @error set.
+ */
- **/
 gunichar *
 g_utf16_to_ucs4 (const gunichar2  *str,
 		 glong             len,              
@@ -1249,14 +1239,13 @@ g_utf16_to_ucs4 (const gunichar2  *str,
  * @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.
+ * @items_read: (allow-none): location to store number of bytes read,
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
+ *     returned in case @str contains a trailing partial character. If
- *              character. If an error occurs then the index of the
+ *     an error occurs then the index of the invalid input is stored here.
- *              invalid input is stored here.
+ * @items_written: (allow-none): location to store number of #gunichar2
- * @items_written: (allow-none): location to store number of <type>gunichar2</type> written,
+ *     written, or %NULL. The value stored here does not include the
- *                 or %NULL.
+ *     trailing 0.
- *                 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.
@@ -1265,10 +1254,9 @@ g_utf16_to_ucs4 (const gunichar2  *str,
  * 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
+ *     This value must be freed with g_free(). If an error occurs,
- *               error occurs, %NULL will be returned and
+ *     %NULL will be returned and @error set.
- *               @error set.
+ */
- **/
 gunichar2 *
 g_utf8_to_utf16 (const gchar *str,
 		 glong        len,
@@ -1368,12 +1356,12 @@ g_utf8_to_utf16 (const gchar *str,
  * @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.
+ * @items_read: (allow-none): location to store number of bytes read,
- *              If an error occurs then the index of the invalid input
+ *     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> 
+ * @items_written: (allow-none): location to store number of #gunichar2 
- *                 written, or %NULL. The value stored here does not 
+ *     written, or %NULL. The value stored here does not include the
- *                 include the trailing 0.
+ *     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.
@@ -1382,10 +1370,9 @@ g_utf8_to_utf16 (const gchar *str,
  * 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
+ *     This value must be freed with g_free(). If an error occurs,
- *               error occurs, %NULL will be returned and
+ *     %NULL will be returned and @error set.
- *               @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,    
@@ -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
  */