From fc04275a007ff2b450d78cfa002a303ba5e2d9d0 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 31 Jan 2014 05:58:17 -0500 Subject: [PATCH] Docs: don't use the type tag Just avoid explicit docbook markup. --- gio/gcredentials.c | 12 +-- gio/ginetsocketaddress.c | 4 +- gio/gsocketaddress.c | 38 ++++--- gio/gunixsocketaddress.c | 2 +- glib/docs.c | 46 ++++----- glib/gdate.c | 2 +- glib/gstrfuncs.c | 66 ++++++------ glib/gutf8.c | 259 ++++++++++++++++++++++------------------------- 8 files changed, 203 insertions(+), 226 deletions(-) diff --git a/gio/gcredentials.c b/gio/gcredentials.c index 8e9f28a..dddf014 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 struct ucred - * - see the - * unix7 - * 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 struct cmsgcred. This corresponds + * credential type is a struct cmsgcred. This corresponds * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. * - * On OpenBSD, the native credential type is a struct sockpeercred. + * 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 ucred_t. 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 87b0d49..9d0f1cd 100644 --- a/gio/ginetsocketaddress.c +++ b/gio/ginetsocketaddress.c @@ -44,8 +44,8 @@ /** * GInetSocketAddress: * - * An IPv4 or IPv6 socket address, corresponding to a struct - * sockaddr_in or struct sockaddr_in6. + * 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 844035f..c1298b3 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 struct sockaddr - * 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 struct sockaddr + * 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 struct sockaddr. + * 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 struct sockaddr 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 - * struct sockaddr. + * 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 struct - * sockaddr, 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 struct sockaddr + * @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 - * struct sockaddr @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 41e751c..96974bb 100644 --- a/gio/gunixsocketaddress.c +++ b/gio/gunixsocketaddress.c @@ -55,7 +55,7 @@ * GUnixSocketAddress: * * A UNIX-domain (local) socket address, corresponding to a - * struct sockaddr_un. + * struct sockaddr_un. */ enum diff --git a/glib/docs.c b/glib/docs.c index 6ca8c48..f74f783 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 void*. + * #gpointer looks better and is easier to use than void*. */ /** @@ -81,19 +80,19 @@ /** * gchar: * - * Corresponds to the standard C char type. + * Corresponds to the standard C char type. */ /** * guchar: * - * Corresponds to the standard C unsigned char type. + * Corresponds to the standard C unsigned char type. */ /** * gint: * - * Corresponds to the standard C int 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 unsigned int 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 short 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 unsigned short 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 long 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 unsigned long 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 float 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 double 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 size_t 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 - * ssize_t 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 off64_t. + * 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 intptr_t, + * 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 uintptr_t, + * 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 va_list variable to place a copy of @ap2 in - * @ap2: a va_list + * @ap1: the va_list variable to place a copy of @ap2 in + * @ap2: a va_list * - * Portable way to copy va_list variables. + * Portable way to copy va_list variables. * - * 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. + * 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 397ec6b..46c9332 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: time_t 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 07a24c0..bf8fa18 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 1f6e359..c0ac8cb 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. * - * - * 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. - * * * 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 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. + * @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 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. + * @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 gunichar2 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 gunichar2 - * 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 */ -- 2.7.4