diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2018-05-23 07:45:46 +0200 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2018-05-23 07:46:20 +0200 |
commit | 0c9ddf99849de21aa8555b7a9fdd45d0d4a7130a (patch) | |
tree | 6bbbde426972c95d945b39a0148dfc550b01c57c /gir | |
parent | dd231b0faf587ff4e0e77519f724214e5876d5c2 (diff) | |
download | gobject-introspection-0c9ddf99849de21aa8555b7a9fdd45d0d4a7130a.tar.gz |
gir: Update annotations to glib 2.57.1
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 31 | ||||
-rw-r--r-- | gir/glib-2.0.c | 217 | ||||
-rw-r--r-- | gir/gobject-2.0.c | 8 |
3 files changed, 207 insertions, 49 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 8b2d34c1..b3c23eee 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -973,7 +973,7 @@ * @manager: The #GDBusObjectManagerClient emitting the signal. * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing. * @interface_proxy: The #GDBusProxy that has properties that are changing. - * @changed_properties: A #GVariant containing the properties that changed. + * @changed_properties: A #GVariant containing the properties that changed (type: `a{sv}`). * @invalidated_properties: (array zero-terminated=1) (element-type utf8): A %NULL terminated * array of properties that were invalidated. * @@ -1170,7 +1170,7 @@ /** * GDBusProxy::g-properties-changed: * @proxy: The #GDBusProxy emitting the signal. - * @changed_properties: A #GVariant containing the properties that changed + * @changed_properties: A #GVariant containing the properties that changed (type: `a{sv}`) * @invalidated_properties: A %NULL terminated array of properties that was invalidated * * Emitted when one or more D-Bus properties on @proxy changes. The @@ -21247,7 +21247,8 @@ * (i.e. a desktop id of kde-foo.desktop will match * `/usr/share/applications/kde/foo.desktop`). * - * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id + * Returns: (nullable): a new #GDesktopAppInfo, or %NULL if no desktop + * file with that id exists. */ @@ -21258,7 +21259,7 @@ * * Creates a new #GDesktopAppInfo. * - * Returns: a new #GDesktopAppInfo or %NULL on error. + * Returns: (nullable): a new #GDesktopAppInfo or %NULL on error. */ @@ -21268,7 +21269,7 @@ * * Creates a new #GDesktopAppInfo. * - * Returns: a new #GDesktopAppInfo or %NULL on error. + * Returns: (nullable): a new #GDesktopAppInfo or %NULL on error. * Since: 2.18 */ @@ -24084,7 +24085,7 @@ * @value_p: (not nullable): pointer to the value * * Sets the @attribute to contain the given value, if possible. To unset the - * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type. + * attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type. */ @@ -24494,7 +24495,7 @@ * * Checks to see if a file is native to the platform. * - * A native file s one expressed in the platform-native filename format, + * A native file is one expressed in the platform-native filename format, * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, * as it might be on a locally mounted remote filesystem. * @@ -41659,6 +41660,22 @@ /** + * g_unix_mount_get_options: + * @mount_entry: a #GUnixMountEntry. + * + * Gets a comma-separated list of mount options for the unix mount. For example, + * `rw,relatime,seclabel,data=ordered`. + * + * This is similar to g_unix_mount_point_get_options(), but it takes + * a #GUnixMountEntry as an argument. + * + * Returns: (nullable): a string containing the options, or %NULL if not + * available. + * Since: 2.58 + */ + + +/** * g_unix_mount_guess_can_eject: * @mount_entry: a #GUnixMountEntry * diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index a9cc893c..725867c4 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -3410,6 +3410,26 @@ /** + * G_GNUC_NO_INLINE: + * + * Expands to the GNU C `noinline` function attribute if the compiler is gcc. + * If the compiler is not gcc, this macro expands to nothing. + * + * Declaring a function as `noinline` prevents the function from being + * considered for inlining. + * + * The attribute may be placed before the declaration, right before the + * `static` keyword. + * + * See the + * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute) + * for more details. + * + * Since: 2.58 + */ + + +/** * G_GNUC_NO_INSTRUMENT: * * Expands to the GNU C no_instrument_function function attribute if the @@ -7727,6 +7747,9 @@ * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], * or simply pointers to any type of data. * + * As with all other GLib data structures, #GQueue is not thread-safe. + * For a thread-safe queue, use #GAsyncQueue. + * * To create a new GQueue, use g_queue_new(). * * To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or @@ -8532,6 +8555,12 @@ * GLib also defines macros for the limits of some of the standard * integer and floating point types, as well as macros for suitable * printf() formats for these types. + * + * Note that depending on the platform and build configuration, the format + * macros might not be compatible with the system provided printf() function, + * because GLib might use a different printf() implementation internally. + * The format macros will always work with GLib API (like g_print()), and with + * any C99 compatible printf() implementation. */ @@ -12248,6 +12277,33 @@ /** + * g_canonicalize_filename: + * @filename: (type filename): the name of the file + * @relative_to: (type filename) (nullable): the relative directory, or %NULL + * to use the current working directory + * + * Gets the canonical file name from @filename. All triple slashes are turned into + * single slashes, and all `..` and `.`s resolved against @relative_to. + * + * Symlinks are not followed, and the returned path is guaranteed to be absolute. + * + * If @filename is an absolute path, @relative_to is ignored. Otherwise, + * @relative_to will be prepended to @filename to make it absolute. @relative_to + * must be an absolute path, or %NULL. If @relative_to is %NULL, it'll fallback + * to g_get_current_dir(). + * + * This function never fails, and will canonicalize file paths even if they don't + * exist. + * + * No file system I/O is done. + * + * Returns: (type filename) (transfer full): a newly allocated string with the + * canonical file path + * Since: 2.58 + */ + + +/** * g_chdir: * @path: (type filename): a pathname in the GLib file name encoding * (UTF-8 on Windows) @@ -13019,13 +13075,16 @@ * into the format string (as with printf()) * * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). - * It's more or less application-defined what constitutes - * a critical vs. a regular warning. You could call - * g_log_set_always_fatal() to make critical warnings exit - * the program, then use g_critical() for fatal errors, for - * example. * - * You can also make critical warnings fatal at runtime by + * Critical warnings are intended to be used in the event of an error + * that originated in the current process (a programmer error). + * Logging of a critical error is by definition an indication of a bug + * somewhere in the current program (or its libraries). + * + * g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and + * g_return_val_if_reached() log at %G_LOG_LEVEL_CRITICAL. + * + * You can make critical warnings fatal at runtime by * setting the `G_DEBUG` environment variable (see * [Running GLib Applications](glib-running.html)): * @@ -13033,6 +13092,8 @@ * G_DEBUG=fatal-warnings gdb ./my-program * ]| * + * You can also use g_log_set_always_fatal(). + * * Any unrelated failures can be skipped over in * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. * @@ -17068,6 +17129,31 @@ /** + * g_hash_table_steal_extended: + * @hash_table: a #GHashTable + * @lookup_key: the key to look up + * @stolen_key: (out) (optional) (transfer full): return location for the + * original key + * @stolen_value: (out) (optional) (nullable) (transfer full): return location + * for the value associated with the key + * + * Looks up a key in the #GHashTable, stealing the original key and the + * associated value and returning %TRUE if the key was found. If the key was + * not found, %FALSE is returned. + * + * If found, the stolen key and value are removed from the hash table without + * calling the key and value destroy functions, and ownership is transferred to + * the caller of this method; as with g_hash_table_steal(). + * + * You can pass %NULL for @lookup_key, provided the hash and equal functions + * of @hash_table are %NULL-safe. + * + * Returns: %TRUE if the key was found in the #GHashTable + * Since: 2.58 + */ + + +/** * g_hash_table_thaw: * @hash_table: a #GHashTable * @@ -20134,6 +20220,11 @@ * g_log_set_writer_func(). See * [Using Structured Logging][using-structured-logging]. * + * This function is mostly intended to be used with + * %G_LOG_LEVEL_CRITICAL. You should typically not set + * %G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or + * %G_LOG_LEVEL_DEBUG as fatal except inside of test programs. + * * Returns: the old fatal mask for the log domain */ @@ -24136,9 +24227,10 @@ * Removes the pointer at the given index from the pointer array. * The following elements are moved down one place. If @array has * a non-%NULL #GDestroyNotify function it is called for the removed - * element. + * element. If so, the return value from this function will potentially point + * to freed memory (depending on the #GDestroyNotify implementation). * - * Returns: the pointer which was removed + * Returns: (nullable): the pointer which was removed */ @@ -24151,9 +24243,11 @@ * The last element in the array is used to fill in the space, so * this function does not preserve the order of the array. But it * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL - * #GDestroyNotify function it is called for the removed element. + * #GDestroyNotify function it is called for the removed element. If so, the + * return value from this function will potentially point to freed memory + * (depending on the #GDestroyNotify implementation). * - * Returns: the pointer which was removed + * Returns: (nullable): the pointer which was removed */ @@ -24248,6 +24342,38 @@ /** + * g_ptr_array_steal_index: + * @array: a #GPtrArray + * @index_: the index of the pointer to steal + * + * Removes the pointer at the given index from the pointer array. + * The following elements are moved down one place. The #GDestroyNotify for + * @array is *not* called on the removed element; ownership is transferred to + * the caller of this function. + * + * Returns: (transfer full) (nullable): the pointer which was removed + * Since: 2.58 + */ + + +/** + * g_ptr_array_steal_index_fast: + * @array: a #GPtrArray + * @index_: the index of the pointer to steal + * + * Removes the pointer at the given index from the pointer array. + * The last element in the array is used to fill in the space, so + * this function does not preserve the order of the array. But it + * is faster than g_ptr_array_steal_index(). The #GDestroyNotify for @array is + * *not* called on the removed element; ownership is transferred to the caller + * of this function. + * + * Returns: (transfer full) (nullable): the pointer which was removed + * Since: 2.58 + */ + + +/** * g_ptr_array_unref: * @array: A #GPtrArray * @@ -25195,7 +25321,7 @@ /** * g_regex_escape_string: * @string: (array length=length): the string to escape - * @length: the length of @string, or -1 if @string is nul-terminated + * @length: the length of @string, in bytes, or -1 if @string is nul-terminated * * Escapes the special characters used for regular expressions * in @string, for instance "a.b*c" becomes "a\.b\*c". This @@ -25317,11 +25443,13 @@ * @match_info: (out) (optional): pointer to location where to store * the #GMatchInfo, or %NULL if you do not need it * - * Scans for a match in string for the pattern in @regex. + * Scans for a match in @string for the pattern in @regex. * The @match_options are combined with the match options specified * when the @regex structure was created, letting you have more * flexibility in reusing #GRegex structures. * + * Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. + * * A #GMatchInfo structure, used to get information on the match, * is stored in @match_info if not %NULL. Note that if @match_info * is not %NULL then it is created even if the function returns %FALSE, @@ -25393,7 +25521,7 @@ * g_regex_match_all_full: * @regex: a #GRegex structure from g_regex_new() * @string: (array length=string_len): the string to scan for matches - * @string_len: the length of @string, or -1 if @string is nul-terminated + * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated * @start_position: starting index of the string to match, in bytes * @match_options: match options * @match_info: (out) (optional): pointer to location where to store @@ -25401,7 +25529,7 @@ * @error: location to store the error occurring, or %NULL to ignore errors * * Using the standard algorithm for regular expression matching only - * the longest match in the string is retrieved, it is not possible + * the longest match in the @string is retrieved, it is not possible * to obtain all the available matches. For instance matching * "<a> <b> <c>" against the pattern "<.*>" * you get "<a> <b> <c>". @@ -25427,6 +25555,8 @@ * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern * that begins with any kind of lookbehind assertion, such as "\b". * + * Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. + * * A #GMatchInfo structure, used to get information on the match, is * stored in @match_info if not %NULL. Note that if @match_info is * not %NULL then it is created even if the function returns %FALSE, @@ -25446,14 +25576,14 @@ * g_regex_match_full: * @regex: a #GRegex structure from g_regex_new() * @string: (array length=string_len): the string to scan for matches - * @string_len: the length of @string, or -1 if @string is nul-terminated + * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated * @start_position: starting index of the string to match, in bytes * @match_options: match options * @match_info: (out) (optional): pointer to location where to store * the #GMatchInfo, or %NULL if you do not need it * @error: location to store the error occurring, or %NULL to ignore errors * - * Scans for a match in string for the pattern in @regex. + * Scans for a match in @string for the pattern in @regex. * The @match_options are combined with the match options specified * when the @regex structure was created, letting you have more * flexibility in reusing #GRegex structures. @@ -25462,6 +25592,8 @@ * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern * that begins with any kind of lookbehind assertion, such as "\b". * + * Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. + * * A #GMatchInfo structure, used to get information on the match, is * stored in @match_info if not %NULL. Note that if @match_info is * not %NULL then it is created even if the function returns %FALSE, @@ -25562,7 +25694,7 @@ * g_regex_replace: * @regex: a #GRegex structure * @string: (array length=string_len): the string to perform matches against - * @string_len: the length of @string, or -1 if @string is nul-terminated + * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated * @start_position: starting index of the string to match, in bytes * @replacement: text to replace each match with * @match_options: options for the match @@ -25604,7 +25736,7 @@ * g_regex_replace_eval: * @regex: a #GRegex structure from g_regex_new() * @string: (array length=string_len): string to perform matches against - * @string_len: the length of @string, or -1 if @string is nul-terminated + * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated * @start_position: starting index of the string to match, in bytes * @match_options: options for the match * @eval: a function to call for each match @@ -25666,7 +25798,7 @@ * g_regex_replace_literal: * @regex: a #GRegex structure * @string: (array length=string_len): the string to perform matches against - * @string_len: the length of @string, or -1 if @string is nul-terminated + * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated * @start_position: starting index of the string to match, in bytes * @replacement: text to replace each match with * @match_options: options for the match @@ -25720,7 +25852,7 @@ * g_regex_split_full: * @regex: a #GRegex structure * @string: (array length=string_len): the string to split with the pattern - * @string_len: the length of @string, or -1 if @string is nul-terminated + * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated * @start_position: starting index of the string to match, in bytes * @match_options: match time option flags * @max_tokens: the maximum number of tokens to split @string into. @@ -26475,14 +26607,14 @@ * @cmp_func: the function used to compare items in the sequence * @cmp_data: user data passed to @cmp_func. * - * Inserts @data into @sequence using @func to determine the new + * Inserts @data into @seq using @cmp_func to determine the new * position. The sequence must already be sorted according to @cmp_func; * otherwise the new position of @data is undefined. * - * @cmp_func is called with two items of the @seq and @user_data. + * @cmp_func is called with two items of the @seq, and @cmp_data. * It should return 0 if the items are equal, a negative value * if the first item comes before the second, and a positive value - * if the second item comes before the first. + * if the second item comes before the first. * * Note that when adding a large amount of data to a #GSequence, * it is more efficient to do unsorted insertions and then call @@ -26498,7 +26630,7 @@ * @seq: a #GSequence * @data: data for the new item * @iter_cmp: the function used to compare iterators in the sequence - * @cmp_data: user data passed to @cmp_func + * @cmp_data: user data passed to @iter_cmp * * Like g_sequence_insert_sorted(), but uses * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as @@ -26509,11 +26641,6 @@ * value if the first iterator comes before the second, and a * positive value if the second iterator comes before the first. * - * It is called with two iterators pointing into @seq. It should - * return 0 if the iterators are equal, a negative value if the - * first iterator comes before the second, and a positive value - * if the second iterator comes before the first. - * * Note that when adding a large amount of data to a #GSequence, * it is more efficient to do unsorted insertions and then call * g_sequence_sort() or g_sequence_sort_iter(). @@ -26652,7 +26779,7 @@ * returned. In that case, you can use g_sequence_iter_next() and * g_sequence_iter_prev() to get others. * - * @cmp_func is called with two items of the @seq and @user_data. + * @cmp_func is called with two items of the @seq, and @cmp_data. * It should return 0 if the items are equal, a negative value if * the first item comes before the second, and a positive value if * the second item comes before the first. @@ -26686,7 +26813,7 @@ * unsorted. * * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of - * the first item found equal to @data according to @cmp_func + * the first item found equal to @data according to @iter_cmp * and @cmp_data, or %NULL if no such item exists * Since: 2.28 */ @@ -26713,13 +26840,13 @@ * @begin: a #GSequenceIter * @end: a #GSequenceIter * - * Inserts the (@begin, @end) range at the destination pointed to by ptr. + * Inserts the (@begin, @end) range at the destination pointed to by @dest. * The @begin and @end iters must point into the same sequence. It is * allowed for @dest to point to a different sequence than the one pointed * into by @begin and @end. * - * If @dest is NULL, the range indicated by @begin and @end is - * removed from the sequence. If @dest iter points to a place within + * If @dest is %NULL, the range indicated by @begin and @end is + * removed from the sequence. If @dest points to a place within * the (@begin, @end) range, the range does not move. * * Since: 2.14 @@ -26807,7 +26934,7 @@ * Returns an iterator pointing to the position where @data would * be inserted according to @cmp_func and @cmp_data. * - * @cmp_func is called with two items of the @seq and @user_data. + * @cmp_func is called with two items of the @seq, and @cmp_data. * It should return 0 if the items are equal, a negative value if * the first item comes before the second, and a positive value if * the second item comes before the first. @@ -26888,12 +27015,13 @@ * @cmp_func: the function used to compare items in the sequence * @cmp_data: user data passed to @cmp_func. * - * Moves the data pointed to a new position as indicated by @cmp_func. This + * Moves the data pointed to by @iter to a new position as indicated by + * @cmp_func. This * function should be called for items in a sequence already sorted according * to @cmp_func whenever some aspect of an item changes so that @cmp_func * may return different values for that item. * - * @cmp_func is called with two items of the @seq and @user_data. + * @cmp_func is called with two items of the @seq, and @cmp_data. * It should return 0 if the items are equal, a negative value if * the first item comes before the second, and a positive value if * the second item comes before the first. @@ -26912,7 +27040,8 @@ * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as * the compare function. * - * @iter_cmp is called with two iterators pointing into @seq. It should + * @iter_cmp is called with two iterators pointing into the #GSequence that + * @iter points into. It should * return 0 if the iterators are equal, a negative value if the first * iterator comes before the second, and a positive value if the second * iterator comes before the first. @@ -26928,7 +27057,7 @@ * @cmp_data: user data passed to @cmp_func * * Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead - * of a GCompareDataFunc as the compare function + * of a #GCompareDataFunc as the compare function * * @cmp_func is called with two iterators pointing into @seq. It should * return 0 if the iterators are equal, a negative value if the first @@ -37738,6 +37867,16 @@ * preferred for that instead, as it allows calling functions to perform actions * conditional on the type of error. * + * Warning messages are intended to be used in the event of unexpected + * external conditions (system misconfiguration, missing files, + * other trusted programs violating protocol, invalid contents in + * trusted files, etc.) + * + * If attempting to deal with programmer errors (for example, incorrect function + * parameters) then you should use %G_LOG_LEVEL_CRITICAL instead. + * + * g_warn_if_reached() and g_warn_if_fail() log at %G_LOG_LEVEL_WARNING. + * * You can make warnings fatal at runtime by setting the `G_DEBUG` * environment variable (see * [Running GLib Applications](glib-running.html)): diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 44b5761b..e9450fc8 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -64,7 +64,7 @@ * in ::notify being emitted, even if the new value is the same as the old. * If they did pass %G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only * when they explicitly call g_object_notify() or g_object_notify_by_pspec(), - * and common practice is to avoid doing so if the value remained unchanged. + * and common practice is to do that only when the value has actually changed. * * This signal is typically used to obtain change notification for a * single property, by specifying the property name as a detail in the @@ -273,7 +273,9 @@ * library provides the #GCClosure type for this purpose. Bindings for * other languages need marshallers which convert between #GValues * and suitable representations in the runtime of the language in - * order to use functions written in that languages as callbacks. + * order to use functions written in that language as callbacks. Use + * g_closure_set_marshal() to set the marshaller on such a custom + * closure implementation. * * Within GObject, closures play an important role in the * implementation of signals. When a signal is registered, the @@ -4833,7 +4835,7 @@ * Creates a new signal. (This is usually done in the class initializer.) * * This is a variant of g_signal_new() that takes a C callback instead - * off a class offset for the signal's class handler. This function + * of a class offset for the signal's class handler. This function * doesn't need a function pointer exposed in the class structure of * an object definition, instead the function pointer is passed * directly and can be overriden by derived classes with |