From 3fd240df6f08b651c4a9123835022b586c852a1e Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Thu, 24 Apr 2014 12:24:09 +0200 Subject: Update glib annotations from git master --- gir/gio-2.0.c | 93 ++++++++++++++++++++++++------------------------------- gir/glib-2.0.c | 38 ++++++++++++++++------- gir/gobject-2.0.c | 3 ++ 3 files changed, 69 insertions(+), 65 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index f4c5ba21..4f1b0f57 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -18,7 +18,7 @@ * GAction:name: * * The name of the action. This is mostly meaningful for identifying - * the action once it has been added to a #GActionGroup. + * the action once it has been added to a #GActionGroup. It is immutable. * * Since: 2.28 */ @@ -28,7 +28,8 @@ * GAction:parameter-type: * * The type of the parameter that must be given when activating the - * action. + * action. This is immutable, and may be %NULL if no parameter is needed when + * activating the action. * * Since: 2.28 */ @@ -47,7 +48,7 @@ * GAction:state-type: * * The #GVariantType of the state that the action has, or %NULL if the - * action is stateless. + * action is stateless. This is immutable. * * Since: 2.28 */ @@ -3680,7 +3681,7 @@ * (using g_file_get_path()) when using g_app_info_launch() even if * the application requested an URI and not a POSIX path. For example * for an desktop-file based application with Exec key `totem - * \%U` and a single URI, `sftp://foo/file.avi`, then + * %U` and a single URI, `sftp://foo/file.avi`, then * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will * only work if a set of suitable GIO extensions (such as gvfs 2.26 * compiled with FUSE support), is available and operational; if this @@ -6944,6 +6945,10 @@ * account the fact that your program will not automatically be killed * if it tries to write to %stdout after it has been closed. * + * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use + * a #GSocket concurrently from multiple threads, you must implement your own + * locking. + * * Since: 2.22 */ @@ -19408,8 +19413,9 @@ * asynchronously. For details of the behaviour, see g_file_copy(). * * If @progress_callback is not %NULL, then that function that will be called - * just like in g_file_copy(), however the callback will run in the main loop, - * not in the thread that is doing the I/O operation. + * just like in g_file_copy(). The callback will run in the default main context + * of the thread calling g_file_copy_async() — the same context as @callback is + * run in. * * When the operation is finished, @callback will be called. You can then call * g_file_copy_finish() to get the result of the operation. @@ -23387,7 +23393,7 @@ * (such as `/path/to/my icon.png`) without escaping * if the #GFile for @icon is a native file. If the file is not * native, the returned string is the result of g_file_get_uri() - * (such as `sftp://path/to/my\%20icon.png`). + * (such as `sftp://path/to/my%20icon.png`). * * - If @icon is a #GThemedIcon with exactly one name, the encoding is * simply the name (such as `network-server`). @@ -24284,7 +24290,10 @@ * g_io_error_from_errno: * @err_no: Error number as defined in errno.h. * - * Converts errno.h error codes into GIO error codes. + * Converts errno.h error codes into GIO error codes. The fallback + * value %G_IO_ERROR_FAILED is returned for error codes not currently + * handled (but note that future GLib releases may return a more + * specific value instead). * * Returns: #GIOErrorEnum value for the given errno.h error number. */ @@ -24294,9 +24303,15 @@ * g_io_error_from_win32_error: * @error_code: Windows error number. * - * Converts some common error codes into GIO error codes. The - * fallback value G_IO_ERROR_FAILED is returned for error codes not - * handled. + * Converts some common error codes (as returned from GetLastError() + * or WSAGetLastError()) into GIO error codes. The fallback value + * %G_IO_ERROR_FAILED is returned for error codes not currently + * handled (but note that future GLib releases may return a more + * specific value instead). + * + * You can use g_win32_error_message() to get a localized string + * corresponding to @error_code. (But note that unlike g_strerror(), + * g_win32_error_message() returns a string that must be freed.) * * Returns: #GIOErrorEnum value for the given error number. * Since: 2.26 @@ -27012,15 +27027,15 @@ * @notification: a #GNotification * @label: label of the button * @action: an action name - * @target_format: (allow-none): a GVariant format string, or %NULL - * @...: positional parameters, as determined by @format_string + * @target_format: (allow-none): a #GVariant format string, or %NULL + * @...: positional parameters, as determined by @target_format * * Adds a button to @notification that activates @action when clicked. * @action must be an application-wide action (it must start with "app."). * * If @target_format is given, it is used to collect remaining - * positional parameters into a GVariant instance, similar to - * g_variant_new(). @action will be activated with that GVariant as its + * positional parameters into a #GVariant instance, similar to + * g_variant_new(). @action will be activated with that #GVariant as its * parameter. * * Since: 2.40 @@ -27032,7 +27047,7 @@ * @notification: a #GNotification * @label: label of the button * @action: an action name - * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL + * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL * * Adds a button to @notification that activates @action when clicked. * @action must be an application-wide action (it must start with "app."). @@ -27096,16 +27111,16 @@ * g_notification_set_default_action_and_target: (skip) * @notification: a #GNotification * @action: an action name - * @target_format: (allow-none): a GVariant format string, or %NULL - * @...: positional parameters, as determined by @format_string + * @target_format: (allow-none): a #GVariant format string, or %NULL + * @...: positional parameters, as determined by @target_format * * Sets the default action of @notification to @action. This action is * activated when the notification is clicked on. It must be an * application-wide action (it must start with "app."). * * If @target_format is given, it is used to collect remaining - * positional parameters into a GVariant instance, similar to - * g_variant_new(). @action will be activated with that GVariant as its + * positional parameters into a #GVariant instance, similar to + * g_variant_new(). @action will be activated with that #GVariant as its * parameter. * * When no default action is set, the application that the notification @@ -27119,16 +27134,12 @@ * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target) * @notification: a #GNotification * @action: an action name - * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL + * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL * * Sets the default action of @notification to @action. This action is * activated when the notification is clicked on. It must be an * application-wide action (start with "app."). * - * If @target_format is given, it is used to collect remaining - * positional parameters into a GVariant instance, similar to - * g_variant_new(). - * * If @target is non-%NULL, @action will be activated with @target as * its parameter. * @@ -30277,9 +30288,10 @@ * g_settings_schema_source_list_schemas: * @source: a #GSettingsSchemaSource * @recursive: if we should recurse - * @non_relocatable: (out) (transfer full): the list of non-relocatable - * schemas - * @relocatable: (out) (transfer full): the list of relocatable schemas + * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the + * list of non-relocatable schemas + * @relocatable: (out) (transfer full) (array zero-terminated=1): the list + * of relocatable schemas * * Lists the schemas in a given source. * @@ -38252,31 +38264,6 @@ */ -/** - * get_all_desktop_entries_for_mime_type: - * @mime_type: a mime type. - * @except: NULL or a strv list - * - * Returns all the desktop ids for @mime_type. The desktop files - * are listed in an order so that default applications are listed before - * non-default ones, and handlers for inherited mimetypes are listed - * after the base ones. - * - * Optionally doesn't list the desktop ids given in the @except - * - * Returns: a #GList containing the desktop ids which claim - * to handle @mime_type. - */ - - -/** - * mime_info_cache_reload: - * @dir: directory path which needs reloading. - * - * Reload the mime information for the @dir. - */ - - /************************************************************/ /* THIS FILE IS GENERATED DO NOT EDIT */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 9326bbfa..9c554298 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -5717,7 +5717,11 @@ * - If there's a "generic" or "unknown" error code for unrecoverable * errors it doesn't make sense to distinguish with specific codes, * it should be called __ERROR_FAILED, - * for example %G_SPAWN_ERROR_FAILED. + * for example %G_SPAWN_ERROR_FAILED. In the case of error code + * enumerations that may be extended in future releases, you should + * generally not handle this error code explicitly, but should + * instead treat any unrecognized error code as equivalent to + * FAILED. * * Summary of rules for use of #GError: * @@ -6381,7 +6385,8 @@ * * Both the key and data are arbitrary byte arrays of bytes or characters. * - * Support for HMAC Digests has been added in GLib 2.30. + * Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 + * in GLib 2.42. */ @@ -6522,7 +6527,7 @@ * Key-value pairs generally have the form `key=value`, with the * exception of localized strings, which have the form * `key[locale]=value`, with a locale identifier of the - * form `lang_COUNTRY\@MODIFIER` where `COUNTRY` and `MODIFIER` + * form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER` * are optional. * Space before and after the '=' character are ignored. Newline, tab, * carriage return and backslash characters in value are escaped as \n, @@ -7257,7 +7262,7 @@ * * The g_rand*_range functions will return high quality equally * distributed random numbers, whereas for example the - * `(g_random_int()\%max)` approach often + * `(g_random_int()%max)` approach often * doesn't yield equally distributed numbers. * * GLib changed the seeding algorithm for the pseudo-random number @@ -12887,7 +12892,7 @@ * - \%C: the century number (year/100) as a 2-digit integer (00-99) * - \%d: the day of the month as a decimal number (range 01 to 31) * - \%e: the day of the month as a decimal number (range 1 to 31) - * - \%F: equivalent to `\%Y-\%m-\%d` (the ISO 8601 date format) + * - \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format) * - \%g: the last two digits of the ISO 8601 week-based year as a * decimal number (00-99). This works well with \%V and \%u. * - \%G: the ISO 8601 week-based year as a decimal number. This works @@ -14043,6 +14048,13 @@ * otherwise. In particular, when @error is %NULL, %FALSE will * be returned. * + * If @domain contains a `FAILED` (or otherwise generic) error code, + * you should generally not check for it explicitly, but should + * instead treat any not-explicitly-recognized error code as being + * equilalent to the `FAILED` code. This way, if the domain is + * extended in the future to provide a more specific error code for + * a certain case, your code will still work. + * * Returns: whether @error has @domain and @code */ @@ -15670,6 +15682,8 @@ * will be closed and it won't be possible to call g_hmac_update() * on it anymore. * + * Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. + * * Returns: the newly created #GHmac, or %NULL. * Use g_hmac_unref() to free the memory allocated by it. * Since: 2.30 @@ -30839,7 +30853,7 @@ * * If a character passes the g_unichar_iswide() test then it will also pass * this test, but not the other way around. Note that some characters may - * pas both this test and g_unichar_iszerowidth(). + * pass both this test and g_unichar_iszerowidth(). * * Returns: %TRUE if the character is wide in legacy East Asian locales * Since: 2.12 @@ -35091,12 +35105,12 @@ * g_win32_error_message: * @error: error code. * - * Translate a Win32 error code (as returned by GetLastError()) into - * the corresponding message. The message is either language neutral, - * or in the thread's language, or the user's language, the system's - * language, or US English (see docs for FormatMessage()). The - * returned string is in UTF-8. It should be deallocated with - * g_free(). + * Translate a Win32 error code (as returned by GetLastError() or + * WSAGetLastError()) into the corresponding message. The message is + * either language neutral, or in the thread's language, or the user's + * language, the system's language, or US English (see docs for + * FormatMessage()). The returned string is in UTF-8. It should be + * deallocated with g_free(). * * Returns: newly-allocated error message */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index ea1dbc16..03aacde9 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -1173,6 +1173,9 @@ * A generic marshaller function implemented via * [libffi](http://sourceware.org/libffi/). * + * Normally this function is not passed explicitly to g_signal_new(), + * but used automatically by GLib when specifying a %NULL marshaller. + * * Since: 2.30 */ -- cgit v1.2.1