From 34da52ea73bfa195feec5a1a4cf7b058075229cd Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Mon, 5 Mar 2012 09:44:18 -0500 Subject: Update glib annotations to 2.31.20 --- gir/gio-2.0.c | 120 ++++++++++++++++++++++++++++++++- gir/glib-2.0.c | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- gir/gobject-2.0.c | 114 +++++++++++++++++++++++++++++-- 3 files changed, 416 insertions(+), 15 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 850249a8..356e136d 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -3845,6 +3845,82 @@ */ +/** + * GLIB_VERSION_2_26: + * + * A macro that evaluates to the 2.26 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_2_28: + * + * A macro that evaluates to the 2.28 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_2_30: + * + * A macro that evaluates to the 2.30 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_2_32: + * + * A macro that evaluates to the 2.32 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_MAX_ALLOWED: + * + * A macro that should be defined by the user prior to including + * the glib.h header. + * The definition should be one of the predefined GLib version + * macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... + * + * This macro defines the upper bound for the GLib API to use. + * + * If a function has been introduced in a newer version of GLib, + * it is possible to use this symbol to get compiler warnings when + * trying to use that function. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_MIN_REQUIRED: + * + * A macro that should be defined by the user prior to including + * the glib.h header. + * The definition should be one of the predefined GLib version + * macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... + * + * This macro defines the lower bound for the GLib API to use. + * + * If a function has been deprecated in a newer version of GLib, + * it is possible to use this symbol to avoid the compiler warnings + * without disabling warning for every deprecated function. + * + * Since: 2.32 + */ + + /** * GLoadableIcon: * @@ -5724,6 +5800,15 @@ */ +/** + * GSignalCVaMarshaller: + * + * This is the signature of va_list marshaller functions, an optional + * marshaller that can be used in some situations to avoid + * marshalling the signal argument into GValues. + */ + + /** * GSignalEmissionHook: * @ihint: Signal invocation hint, see #GSignalInvocationHint. @@ -6429,7 +6514,8 @@ * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed. * @G_SPAWN_ERROR_ACCES: execv() returned EACCES * @G_SPAWN_ERROR_PERM: execv() returned EPERM - * @G_SPAWN_ERROR_2BIG: execv() returned E2BIG + * @G_SPAWN_ERROR_TOO_BIG: execv() returned E2BIG + * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG * @G_SPAWN_ERROR_NOEXEC: execv() returned ENOEXEC * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned ENAMETOOLONG * @G_SPAWN_ERROR_NOENT: execv() returned ENOENT @@ -7451,6 +7537,8 @@ * @G_UNICODE_BREAK_HANGUL_LV_SYLLABLE: Hangul LV Syllable (H2) * @G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE: Hangul LVT Syllable (H3) * @G_UNICODE_BREAK_CLOSE_PARANTHESIS: Closing Parenthesis (CP). Since 2.28 + * @G_UNICODE_BREAK_CONDITIONAL_JAPANESE_STARTER: Conditional Japanese Starter (CJ). Since: 2.32 + * @G_UNICODE_BREAK_HEBREW_LETTER: Hebrew Letter (HL). Since: 2.32 * * These are the possible line break classifications. * @@ -7551,6 +7639,13 @@ * @G_UNICODE_SCRIPT_BATAK: Batak. Since 2.28 * @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28 * @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28 + * @G_UNICODE_SCRIPT_CHAKMA: Chakma. Since: 2.32 + * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32 + * @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32 + * @G_UNICODE_SCRIPT_MIAO: Miao. Since: 2.32 + * @G_UNICODE_SCRIPT_SHARADA: Sharada. Since: 2.32 + * @G_UNICODE_SCRIPT_SORA_SOMPENG: Sora Sompeng. Since: 2.32 + * @G_UNICODE_SCRIPT_TAKRI: Takri. Since: 2.32 * * The #GUnicodeScript enumeration identifies different writing * systems. The values correspond to the names as defined in the @@ -12094,6 +12189,24 @@ */ +/** + * G_VOLUME_IDENTIFIER_KIND_CLASS: + * + * The string used to obtain the volume class + * with g_volume_get_identifier(). + * + * Known volume classes include device and + * network. Other classes may be added in the + * future. + * + * This is intended to be used by applications to classify #GVolume + * instances into different sections - for example a file manager or + * file chooser can use this information to show + * network volumes under a "Network" heading and + * device volumes under a "Devices" heading. + */ + + /** * G_VOLUME_IDENTIFIER_KIND_HAL_UDI: * @@ -26389,7 +26502,8 @@ * @type: a #GFileAttributeType * @value_p: pointer to the value * - * Sets the @attribute to contain the given value, if possible. + * Sets the @attribute to contain the given value, if possible. To unset the + * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type. */ @@ -27269,7 +27383,7 @@ * returned by g_get_tmp_dir()) and returns a #GFile and * #GFileIOStream pointing to it. * - * @template should be a string in the GLib file name encoding + * @tmpl should be a string in the GLib file name encoding * containing a sequence of six 'X' characters, and containing no * directory components. If it is %NULL, a default template is used. * diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 62749fd1..fb17fa37 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -1549,6 +1549,15 @@ */ +/** + * GLIB_DISABLE_DEPRECATION_WARNINGS: + * + * A macro that should be defined before including the glib.h header. + * If it is defined, no compiler warnings will be produced for uses + * of deprecated GLib APIs. + */ + + /** * GLIB_MAJOR_VERSION: * @@ -1582,6 +1591,82 @@ */ +/** + * GLIB_VERSION_2_26: + * + * A macro that evaluates to the 2.26 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_2_28: + * + * A macro that evaluates to the 2.28 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_2_30: + * + * A macro that evaluates to the 2.30 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_2_32: + * + * A macro that evaluates to the 2.32 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_MAX_ALLOWED: + * + * A macro that should be defined by the user prior to including + * the glib.h header. + * The definition should be one of the predefined GLib version + * macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... + * + * This macro defines the upper bound for the GLib API to use. + * + * If a function has been introduced in a newer version of GLib, + * it is possible to use this symbol to get compiler warnings when + * trying to use that function. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_MIN_REQUIRED: + * + * A macro that should be defined by the user prior to including + * the glib.h header. + * The definition should be one of the predefined GLib version + * macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... + * + * This macro defines the lower bound for the GLib API to use. + * + * If a function has been deprecated in a newer version of GLib, + * it is possible to use this symbol to avoid the compiler warnings + * without disabling warning for every deprecated function. + * + * Since: 2.32 + */ + + /** * GLONG_FROM_BE: * @val: a #glong value in big-endian byte order @@ -3074,6 +3159,15 @@ */ +/** + * GSignalCVaMarshaller: + * + * This is the signature of va_list marshaller functions, an optional + * marshaller that can be used in some situations to avoid + * marshalling the signal argument into GValues. + */ + + /** * GSignalEmissionHook: * @ihint: Signal invocation hint, see #GSignalInvocationHint. @@ -3264,7 +3358,8 @@ * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed. * @G_SPAWN_ERROR_ACCES: execv() returned EACCES * @G_SPAWN_ERROR_PERM: execv() returned EPERM - * @G_SPAWN_ERROR_2BIG: execv() returned E2BIG + * @G_SPAWN_ERROR_TOO_BIG: execv() returned E2BIG + * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG * @G_SPAWN_ERROR_NOEXEC: execv() returned ENOEXEC * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned ENAMETOOLONG * @G_SPAWN_ERROR_NOENT: execv() returned ENOENT @@ -4240,6 +4335,8 @@ * @G_UNICODE_BREAK_HANGUL_LV_SYLLABLE: Hangul LV Syllable (H2) * @G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE: Hangul LVT Syllable (H3) * @G_UNICODE_BREAK_CLOSE_PARANTHESIS: Closing Parenthesis (CP). Since 2.28 + * @G_UNICODE_BREAK_CONDITIONAL_JAPANESE_STARTER: Conditional Japanese Starter (CJ). Since: 2.32 + * @G_UNICODE_BREAK_HEBREW_LETTER: Hebrew Letter (HL). Since: 2.32 * * These are the possible line break classifications. * @@ -4340,6 +4437,13 @@ * @G_UNICODE_SCRIPT_BATAK: Batak. Since 2.28 * @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28 * @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28 + * @G_UNICODE_SCRIPT_CHAKMA: Chakma. Since: 2.32 + * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32 + * @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32 + * @G_UNICODE_SCRIPT_MIAO: Miao. Since: 2.32 + * @G_UNICODE_SCRIPT_SHARADA: Sharada. Since: 2.32 + * @G_UNICODE_SCRIPT_SORA_SOMPENG: Sora Sompeng. Since: 2.32 + * @G_UNICODE_SCRIPT_TAKRI: Takri. Since: 2.32 * * The #GUnicodeScript enumeration identifies different writing * systems. The values correspond to the names as defined in the @@ -5091,6 +5195,30 @@ */ +/** + * G_DEPRECATED: + * + * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark + * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is + * meant to be portable across different compilers and must be placed + * before the function declaration. + * + * Since: 2.32 + */ + + +/** + * G_DEPRECATED_FOR: + * + * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark + * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it is + * meant to be portable across different compilers and must be placed + * before the function declaration. + * + * Since: 2.32 + */ + + /** * G_DIR_SEPARATOR: * @@ -8866,6 +8994,17 @@ */ +/** + * G_UNAVAILABLE: + * + * This macro can be used to mark a function declaration as unavailable. + * It must be placed before the function declaration. Use of a function + * that has been annotated with this macros will produce a compiler warning. + * + * Since: 2.32 + */ + + /** * G_UNICHAR_MAX_DECOMPOSITION_LENGTH: * @@ -12934,6 +13073,18 @@ * GLib provides version information, primarily useful in configure * checks for builds that have a configure script. Applications will * not typically use the features described here. + * + * The GLib headers annotate deprecated APIs in a way that produces + * compiler warnings if these deprecated APIs are used. The warnings + * can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS + * before including the glib.h header. + * + * GLib also provides support for building applications against + * defined subsets of deprecated or new GLib APIs. Define the macro + * %GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib + * you want to receive warnings about deprecated APIs. Define the + * macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of + * GLib whose API you want to use. */ @@ -24269,7 +24420,7 @@ * with g_mapped_file_unref(), or %NULL if the mapping failed. * * Returns: a newly allocated #GMappedFile which must be unref'd - * Since: 2.30 + * Since: 2.32 */ @@ -29390,6 +29541,14 @@ * the first item comes before the second, and a positive value if * the second item comes before the first. * + * + * This function will fail if the data contained in the sequence is + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. + * + * * first item found equal to @data according to @cmp_func and @cmp_data. * * Returns: an #GSequenceIter pointing to the position of the @@ -29412,6 +29571,14 @@ * if the first iterator comes before the second, and a positive * value if the second iterator comes before the first. * + * + * This function will fail if the data contained in the sequence is + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. + * + * * the first item found equal to @data according to @cmp_func * and @cmp_data. * @@ -29543,6 +29710,14 @@ * If you are simply searching for an existing element of the sequence, * consider using g_sequence_lookup(). * + * + * This function will fail if the data contained in the sequence is + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. + * + * * would have been inserted according to @cmp_func and @cmp_data. * * Returns: an #GSequenceIter pointing to the position where @data @@ -29568,6 +29743,14 @@ * If you are simply searching for an existing element of the sequence, * consider using g_sequence_lookup_iter(). * + * + * This function will fail if the data contained in the sequence is + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. + * + * * where @data would have been inserted according to @iter_cmp * and @cmp_data. * @@ -35541,9 +35724,9 @@ /** * g_uri_unescape_segment: - * @escaped_string: a string. - * @escaped_string_end: a string. - * @illegal_characters: an optional string of illegal characters not to be allowed. + * @escaped_string: (allow-none): A string, may be %NULL + * @escaped_string_end: (allow-none): Pointer to end of @escaped_string, may be %NULL + * @illegal_characters: (allow-none): An optional string of illegal characters not to be allowed, may be %NULL * * Unescapes a segment of an escaped string. * @@ -35553,7 +35736,9 @@ * slash being expanded in an escaped path element, which might confuse pathname * handling. * - * The returned string should be freed when no longer needed. + * The returned string should be freed when no longer needed. As a + * special case if %NULL is given for @escaped_string, this function + * will return %NULL. * * Returns: an unescaped version of @escaped_string or %NULL on error. * Since: 2.16 diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index b7fc6b4c..518936ca 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -606,6 +606,82 @@ */ +/** + * GLIB_VERSION_2_26: + * + * A macro that evaluates to the 2.26 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_2_28: + * + * A macro that evaluates to the 2.28 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_2_30: + * + * A macro that evaluates to the 2.30 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_2_32: + * + * A macro that evaluates to the 2.32 version of GLib, in a format + * that can be used by the C pre-processor. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_MAX_ALLOWED: + * + * A macro that should be defined by the user prior to including + * the glib.h header. + * The definition should be one of the predefined GLib version + * macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... + * + * This macro defines the upper bound for the GLib API to use. + * + * If a function has been introduced in a newer version of GLib, + * it is possible to use this symbol to get compiler warnings when + * trying to use that function. + * + * Since: 2.32 + */ + + +/** + * GLIB_VERSION_MIN_REQUIRED: + * + * A macro that should be defined by the user prior to including + * the glib.h header. + * The definition should be one of the predefined GLib version + * macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... + * + * This macro defines the lower bound for the GLib API to use. + * + * If a function has been deprecated in a newer version of GLib, + * it is possible to use this symbol to avoid the compiler warnings + * without disabling warning for every deprecated function. + * + * Since: 2.32 + */ + + /** * GMainContext: * @@ -1493,6 +1569,15 @@ */ +/** + * GSignalCVaMarshaller: + * + * This is the signature of va_list marshaller functions, an optional + * marshaller that can be used in some situations to avoid + * marshalling the signal argument into GValues. + */ + + /** * GSignalEmissionHook: * @ihint: Signal invocation hint, see #GSignalInvocationHint. @@ -1683,7 +1768,8 @@ * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed. * @G_SPAWN_ERROR_ACCES: execv() returned EACCES * @G_SPAWN_ERROR_PERM: execv() returned EPERM - * @G_SPAWN_ERROR_2BIG: execv() returned E2BIG + * @G_SPAWN_ERROR_TOO_BIG: execv() returned E2BIG + * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG * @G_SPAWN_ERROR_NOEXEC: execv() returned ENOEXEC * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned ENAMETOOLONG * @G_SPAWN_ERROR_NOENT: execv() returned ENOENT @@ -2079,6 +2165,8 @@ * @G_UNICODE_BREAK_HANGUL_LV_SYLLABLE: Hangul LV Syllable (H2) * @G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE: Hangul LVT Syllable (H3) * @G_UNICODE_BREAK_CLOSE_PARANTHESIS: Closing Parenthesis (CP). Since 2.28 + * @G_UNICODE_BREAK_CONDITIONAL_JAPANESE_STARTER: Conditional Japanese Starter (CJ). Since: 2.32 + * @G_UNICODE_BREAK_HEBREW_LETTER: Hebrew Letter (HL). Since: 2.32 * * These are the possible line break classifications. * @@ -2179,6 +2267,13 @@ * @G_UNICODE_SCRIPT_BATAK: Batak. Since 2.28 * @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28 * @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28 + * @G_UNICODE_SCRIPT_CHAKMA: Chakma. Since: 2.32 + * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32 + * @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32 + * @G_UNICODE_SCRIPT_MIAO: Miao. Since: 2.32 + * @G_UNICODE_SCRIPT_SHARADA: Sharada. Since: 2.32 + * @G_UNICODE_SCRIPT_SORA_SOMPENG: Sora Sompeng. Since: 2.32 + * @G_UNICODE_SCRIPT_TAKRI: Takri. Since: 2.32 * * The #GUnicodeScript enumeration identifies different writing * systems. The values correspond to the names as defined in the @@ -9974,6 +10069,8 @@ * MyObject defined in the standard GObject * fashion. * type's class_init() function. + * Note the use of a structure member "priv" to avoid the overhead + * of repeatedly calling MY_OBJECT_GET_PRIVATE(). * * |[ * typedef struct _MyObject MyObject; @@ -10006,7 +10103,11 @@ * static int * my_object_get_some_field (MyObject *my_object) * { - * MyObjectPrivate *priv = my_object->priv; + * MyObjectPrivate *priv; + * + * g_return_val_if_fail (MY_IS_OBJECT (my_object), 0); + * + * priv = my_object->priv; * * return priv->some_field; * } @@ -10651,10 +10752,11 @@ * @flags: Bitwise combination of #GTypeFlags values. * * Registers @type_id as the predefined identifier and @type_name as the - * name of a fundamental type. The type system uses the information - * contained in the #GTypeInfo structure pointed to by @info and the - * #GTypeFundamentalInfo structure pointed to by @finfo to manage the - * type and its instances. The value of @flags determines additional + * name of a fundamental type. If @type_id is already registered, or a type + * named @type_name is already registered, the behaviour is undefined. The type + * system uses the information contained in the #GTypeInfo structure pointed to + * by @info and the #GTypeFundamentalInfo structure pointed to by @finfo to + * manage the type and its instances. The value of @flags determines additional * characteristics of the fundamental type. * * Returns: The predefined type identifier. -- cgit v1.2.1