From: Matthias Clasen Date: Thu, 28 Nov 2002 20:46:29 +0000 (+0000) Subject: Move some docs inline, and add deprecation information. To see the list of X-Git-Url: http://git.openbox.org/?a=commitdiff_plain;h=803bae66a3d1da5a4926ca26e75cbdb1c02e168a;p=dana%2Fcg-glib.git Move some docs inline, and add deprecation information. To see the list of * glib/gutils.c: * glib/gtree.c: * glib/gstring.c: * glib/gstrfuncs.c: * glib/giochannel.c: Move some docs inline, and add deprecation information. To see the list of affected functions, grep for "Deprecated:". * glib/tmpl/strings.sgml: * glib/tmpl/string_utils.sgml: * glib/tmpl/misc_utils.sgml: Move some docs inline. --- diff --git a/ChangeLog b/ChangeLog index dc221692..2b0c109f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,13 @@ 2002-11-28 Matthias Clasen + * glib/gutils.c: + * glib/gtree.c: + * glib/gstring.c: + * glib/gstrfuncs.c: + * glib/giochannel.c: Move some docs inline, and add deprecation + information. To see the list of affected functions, grep for + "Deprecated:". + * configure.in: Fix the definitions around printf: either we use system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and HAVE_UNIX98_PRINTF have already been determined by earlier tests, diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index dc221692..2b0c109f 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,5 +1,13 @@ 2002-11-28 Matthias Clasen + * glib/gutils.c: + * glib/gtree.c: + * glib/gstring.c: + * glib/gstrfuncs.c: + * glib/giochannel.c: Move some docs inline, and add deprecation + information. To see the list of affected functions, grep for + "Deprecated:". + * configure.in: Fix the definitions around printf: either we use system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and HAVE_UNIX98_PRINTF have already been determined by earlier tests, diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index dc221692..2b0c109f 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,5 +1,13 @@ 2002-11-28 Matthias Clasen + * glib/gutils.c: + * glib/gtree.c: + * glib/gstring.c: + * glib/gstrfuncs.c: + * glib/giochannel.c: Move some docs inline, and add deprecation + information. To see the list of affected functions, grep for + "Deprecated:". + * configure.in: Fix the definitions around printf: either we use system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and HAVE_UNIX98_PRINTF have already been determined by earlier tests, diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index dc221692..2b0c109f 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,5 +1,13 @@ 2002-11-28 Matthias Clasen + * glib/gutils.c: + * glib/gtree.c: + * glib/gstring.c: + * glib/gstrfuncs.c: + * glib/giochannel.c: Move some docs inline, and add deprecation + information. To see the list of affected functions, grep for + "Deprecated:". + * configure.in: Fix the definitions around printf: either we use system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and HAVE_UNIX98_PRINTF have already been determined by earlier tests, diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index dc221692..2b0c109f 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,5 +1,13 @@ 2002-11-28 Matthias Clasen + * glib/gutils.c: + * glib/gtree.c: + * glib/gstring.c: + * glib/gstrfuncs.c: + * glib/giochannel.c: Move some docs inline, and add deprecation + information. To see the list of affected functions, grep for + "Deprecated:". + * configure.in: Fix the definitions around printf: either we use system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and HAVE_UNIX98_PRINTF have already been determined by earlier tests, diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index dc221692..2b0c109f 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,5 +1,13 @@ 2002-11-28 Matthias Clasen + * glib/gutils.c: + * glib/gtree.c: + * glib/gstring.c: + * glib/gstrfuncs.c: + * glib/giochannel.c: Move some docs inline, and add deprecation + information. To see the list of affected functions, grep for + "Deprecated:". + * configure.in: Fix the definitions around printf: either we use system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and HAVE_UNIX98_PRINTF have already been determined by earlier tests, diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index dc221692..2b0c109f 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,5 +1,13 @@ 2002-11-28 Matthias Clasen + * glib/gutils.c: + * glib/gtree.c: + * glib/gstring.c: + * glib/gstrfuncs.c: + * glib/giochannel.c: Move some docs inline, and add deprecation + information. To see the list of affected functions, grep for + "Deprecated:". + * configure.in: Fix the definitions around printf: either we use system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and HAVE_UNIX98_PRINTF have already been determined by earlier tests, diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 1c71aea8..30882f11 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +2002-11-28 Matthias Clasen + + * glib/tmpl/strings.sgml: + * glib/tmpl/string_utils.sgml: + * glib/tmpl/misc_utils.sgml: Move some docs inline. + 2002-11-23 Matthias Clasen * gobject/tmpl/gclosure.sgml: diff --git a/docs/reference/glib/tmpl/misc_utils.sgml b/docs/reference/glib/tmpl/misc_utils.sgml index 50f759a5..d8a4b5c4 100644 --- a/docs/reference/glib/tmpl/misc_utils.sgml +++ b/docs/reference/glib/tmpl/misc_utils.sgml @@ -93,19 +93,10 @@ The returned string should be freed when no longer needed. - -This function is deprecated and will be removed in the next major -release of GLib. Use g_path_get_basename() instead. - - -Gets the name of the file without any leading -directory components. It returns a pointer into the given file name -string. - -@file_name: the name of the file. -@Returns: the name of the file without any leading directory components. +@file_name: +@Returns: diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml index 027f33d0..8ea83451 100644 --- a/docs/reference/glib/tmpl/string_utils.sgml +++ b/docs/reference/glib/tmpl/string_utils.sgml @@ -571,73 +571,37 @@ possibly non-ASCII character in. -Converts a string to upper case. This function is totally broken -for the reasons discussed in the g_strncasecmp() docs - -use g_ascii_strup() or g_utf8_strup() instead. -@string: the string to convert. +@string: @Returns: -Converts a string to lower case. This function is totally broken for -the reasons discussed in the g_strncasecmp() docs - use -g_ascii_strdown() or g_utf8_strdown() instead. -@string: the string to convert. +@string: @Returns: -A case-insensitive string comparison, corresponding to the standard -strcasecmp() function on platforms which support it. - - -See g_strncasecmp() for a discussion of why this is deprecated and -how to replace it. -@s1: a string. -@s2: a string to compare with @s1. -@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive -value if @s1 > @s2. +@s1: +@s2: +@Returns: -A case-insensitive string comparison, corresponding to the standard -strncasecmp() function on platforms which support it. -It is similar to g_strcasecmp() except it only compares the first @n characters -of the strings. - - -The problem with g_strncasecmp() is that it does the comparison by -calling toupper()/tolower() -on each byte. toupper()/tolower() are -locale-specific and operate on single bytes. However, it is impossible -to handle things correctly from an i18n standpoint by operating on -bytes, since characters may be multibyte. Thus g_strncasecmp() is -broken if your string is guaranteed to be ASCII, since it's -locale-sensitive, and it's broken if your string is localized, since -it doesn't work on many encodings at all, including UTF-8, EUC-JP, -etc. - - -There are therefore two replacement functions: g_ascii_strncasecmp(), -which only works on ASCII and is not locale-sensitive, and -g_utf8_casefold(), which is good for case-insensitive sorting of -UTF-8. -@s1: a string. -@s2: a string to compare with @s1. -@n: the maximum number of characters to compare. -@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive -value if @s1 > @s2. +@s1: +@s2: +@n: +@Returns: diff --git a/docs/reference/glib/tmpl/strings.sgml b/docs/reference/glib/tmpl/strings.sgml index 45daad7a..bc5cb2aa 100644 --- a/docs/reference/glib/tmpl/strings.sgml +++ b/docs/reference/glib/tmpl/strings.sgml @@ -313,20 +313,18 @@ If @free_segment is %TRUE it also frees the character data. -Converts a #GString to upper case. -@string: a #GString. -@Returns: the #GString. +@string: +@Returns: -Converts a #GString to lower case. -@string: a #GString. -@Returns: the #GString. +@string: +@Returns: diff --git a/glib/giochannel.c b/glib/giochannel.c index 9708b7a8..3091375d 100644 --- a/glib/giochannel.c +++ b/glib/giochannel.c @@ -160,10 +160,11 @@ g_io_error_get_from_g_error (GIOStatus status, * @count: the number of bytes to read from the #GIOChannel. * @bytes_read: returns the number of bytes actually read. * - * Reads data from a #GIOChannel. This function is deprecated. New code should - * use g_io_channel_read_chars() instead. + * Reads data from a #GIOChannel. * * Return value: %G_IO_ERROR_NONE if the operation was successful. + * + * Deprecated: Use g_io_channel_read_chars() instead. **/ GIOError g_io_channel_read (GIOChannel *channel, @@ -195,10 +196,11 @@ g_io_channel_read (GIOChannel *channel, * @count: the number of bytes to write. * @bytes_written: the number of bytes actually written. * - * Writes data to a #GIOChannel. This function is deprecated. New code should - * use g_io_channel_write_chars() instead. + * Writes data to a #GIOChannel. * * Return value: %G_IO_ERROR_NONE if the operation was successful. + * + * Deprecated: Use g_io_channel_write_chars() instead. **/ GIOError g_io_channel_write (GIOChannel *channel, @@ -232,10 +234,11 @@ g_io_channel_write (GIOChannel *channel, * file). * * Sets the current position in the #GIOChannel, similar to the standard library - * function fseek(). This function is deprecated. New - * code should use g_io_channel_seek_position() instead. + * function fseek(). * * Return value: %G_IO_ERROR_NONE if the operation was successful. + * + * Deprecated: Use g_io_channel_seek_position() instead. **/ GIOError g_io_channel_seek (GIOChannel *channel, @@ -296,9 +299,9 @@ g_io_channel_seek (GIOChannel *channel, * * Close an IO channel. Any pending data to be written will be * flushed, ignoring errors. The channel will not be freed until the - * last reference is dropped using g_io_channel_unref(). This - * function is deprecated: you should use g_io_channel_shutdown() - * instead. + * last reference is dropped using g_io_channel_unref(). + * + * Deprecated: Use g_io_channel_shutdown() instead. **/ void g_io_channel_close (GIOChannel *channel) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 905bc055..1c839343 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -1529,6 +1529,18 @@ g_ascii_strup (const gchar *str, return result; } +/** + * g_strdown: + * @string: the string to convert. + * + * Converts a string to lower case. + * + * Return value: the string + * + * Deprecated: This function is totally broken for the reasons discussed in + * the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() + * instead. + **/ gchar* g_strdown (gchar *string) { @@ -1548,6 +1560,17 @@ g_strdown (gchar *string) return (gchar *) string; } +/** + * g_strup: + * @string: the string to convert. + * + * Converts a string to upper case. + * + * Return value: the string + * + * Deprecated: This function is totally broken for the reasons discussed in + * the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead. + **/ gchar* g_strup (gchar *string) { @@ -1764,6 +1787,20 @@ g_ascii_strncasecmp (const gchar *s1, return 0; } +/** + * g_strcasecmp: + * @s1: a string. + * @s2: a string to compare with @s1. + * + * A case-insensitive string comparison, corresponding to the standard + * strcasecmp() function on platforms which support it. + * + * Return value: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. + * + * Deprecated: See g_strncasecmp() for a discussion of why this function is + * deprecated and how to replace it. + **/ gint g_strcasecmp (const gchar *s1, const gchar *s2) @@ -1795,6 +1832,33 @@ g_strcasecmp (const gchar *s1, #endif } +/** + * g_strncasecmp: + * @s1: a string. + * @s2: a string to compare with @s1. + * @n: the maximum number of characters to compare. + * + * A case-insensitive string comparison, corresponding to the standard + * strncasecmp() function on platforms which support it. + * It is similar to g_strcasecmp() except it only compares the first @n + * characters of the strings. + * + * Return value: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. + * + * Deprecated: The problem with g_strncasecmp() is that it does the + * comparison by calling toupper()/tolower(). These functions are + * locale-specific and operate on single bytes. However, it is impossible + * to handle things correctly from an I18N standpoint by operating on + * bytes, since characters may be multibyte. Thus g_strncasecmp() is + * broken if your string is guaranteed to be ASCII, since it's + * locale-sensitive, and it's broken if your string is localized, since + * it doesn't work on many encodings at all, including UTF-8, EUC-JP, + * etc. + * There are therefore two replacement functions: g_ascii_strncasecmp(), + * which only works on ASCII and is not locale-sensitive, and + * g_utf8_casefold(), which is good for case-insensitive sorting of UTF-8. + **/ gint g_strncasecmp (const gchar *s1, const gchar *s2, diff --git a/glib/gstring.c b/glib/gstring.c index aab4f1f8..c92c5a1c 100644 --- a/glib/gstring.c +++ b/glib/gstring.c @@ -669,6 +669,18 @@ g_string_ascii_up (GString *string) return string; } +/** + * g_string_down: + * @string: a #GString + * + * Converts a #GString to lowercase. + * + * Returns: the #GString. + * + * Deprecated: This function uses the locale-specific tolower() function, + * which is almost never the right thing. Use g_string_ascii_down() or + * g_utf8_strdown() instead. + */ GString* g_string_down (GString *string) { @@ -690,6 +702,18 @@ g_string_down (GString *string) return string; } +/** + * g_string_up: + * @string: a #GString + * + * Converts a #GString to uppercase. + * + * Return value: the #GString + * + * Deprecated: This function uses the locale-specific toupper() function, + * which is almost never the right thing. Use g_string_ascii_up() or + * g_utf8_strup() instead. + **/ GString* g_string_up (GString *string) { diff --git a/glib/gtree.c b/glib/gtree.c index 31e941af..2e4f99a7 100644 --- a/glib/gtree.c +++ b/glib/gtree.c @@ -471,9 +471,10 @@ g_tree_foreach (GTree *tree, * %G_PRE_ORDER and %G_POST_ORDER. * @user_data: user data to pass to the function. * - * Calls the given function for each node in the #GTree. This function is - * deprecated, since the order of a balanced tree is somewhat arbitrary. - * If you just want to visit all nodes in sorted order, use g_tree_foreach() + * Calls the given function for each node in the #GTree. + * + * Deprecated: The order of a balanced tree is somewhat arbitrary. If you + * just want to visit all nodes in sorted order, use g_tree_foreach() * instead. If you really need to visit nodes in a different order, consider * using an N-ary Tree. **/ diff --git a/glib/gutils.c b/glib/gutils.c index 344947dc..060d2791 100644 --- a/glib/gutils.c +++ b/glib/gutils.c @@ -383,6 +383,17 @@ g_parse_debug_string (const gchar *string, return result; } +/** + * g_basename: + * @file_name: the name of the file. + * + * Gets the name of the file without any leading directory components. + * It returns a pointer into the given file name string. + * + * Return value: the name of the file without any leading directory components. + * + * Deprecated: Use g_path_get_basename() instead. + **/ G_CONST_RETURN gchar* g_basename (const gchar *file_name) {