diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2013-11-26 19:55:17 +0100 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2013-11-26 19:55:17 +0100 |
commit | 9112ec1e845015a17bba49fb1dd385a2c6e9efd7 (patch) | |
tree | 77f5959b06536a66d6790ade588243becb6632ee /gir | |
parent | ff2e8dd92d43e11705fcd2b493737bb58c4f2daa (diff) | |
download | gobject-introspection-9112ec1e845015a17bba49fb1dd385a2c6e9efd7.tar.gz |
Update glib annotations from git master
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 105 | ||||
-rw-r--r-- | gir/glib-2.0.c | 108 | ||||
-rw-r--r-- | gir/gmodule-2.0.c | 6 | ||||
-rw-r--r-- | gir/gobject-2.0.c | 42 |
4 files changed, 195 insertions, 66 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index a8dc63b7..4ca1f234 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -2540,7 +2540,8 @@ * @client is about to make a connection to a remote host; * either a proxy server or the destination server itself. * @connection is the #GSocketConnection, which is not yet - * connected. + * connected. Since GLib 2.40, you can access the remote + * address via g_socket_connection_get_remote_address(). * </para></listitem> * </varlistentry> * <varlistentry> @@ -3495,7 +3496,7 @@ * organized fashion. * * An extension point is identified by a name, and it may optionally - * require that any implementation must by of a certain type (or derived + * require that any implementation must be of a certain type (or derived * thereof). Use g_io_extension_point_register() to register an * extension point, and g_io_extension_point_set_required_type() to * set a required type. @@ -18561,6 +18562,8 @@ * applications that matched @search_string with an equal score. The * outer list is sorted by score so that the first strv contains the * best-matching applications, and so on. + * The algorithm for determining matches is undefined and may change at + * any time. * * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a * list of strvs. Free each item with g_strfreev() and free the outer @@ -20215,8 +20218,9 @@ * This call does no blocking I/O. * * Returns: string with the relative path from @descendant - * to @parent. The returned string should be freed with - * g_free() when no longer needed. + * to @parent, or %NULL if @descendant doesn't have @parent + * as prefix. The returned string should be freed with g_free() + * when no longer needed. */ @@ -27324,6 +27328,34 @@ /** + * g_output_stream_printf: + * @stream: a #GOutputStream. + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore + * @format: the format string. See the printf() documentation + * @...: the parameters to insert into the format string + * + * This is a utility function around g_output_stream_write_all(). It + * uses g_strdup_vprintf() to turn @format and @... into a string that + * is then written to @stream. + * + * See the documentation of g_output_stream_write_all() about the + * behavior of the actual write operation. + * + * Note that partial writes cannot be properly checked with this + * function due to the variable length of the written string, if you + * need precise control over partial write failures, you need to + * create you own printf()-like wrapper around g_output_stream_write() + * or g_output_stream_write_all(). + * + * Since: 2.40 + * Returns: %TRUE on success, %FALSE if there was an error + */ + + +/** * g_output_stream_set_pending: * @stream: a #GOutputStream. * @error: a #GError location to store the error occurring, or %NULL to @@ -27393,6 +27425,34 @@ /** + * g_output_stream_vprintf: + * @stream: a #GOutputStream. + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore + * @format: the format string. See the printf() documentation + * @args: the parameters to insert into the format string + * + * This is a utility function around g_output_stream_write_all(). It + * uses g_strdup_vprintf() to turn @format and @args into a string that + * is then written to @stream. + * + * See the documentation of g_output_stream_write_all() about the + * behavior of the actual write operation. + * + * Note that partial writes cannot be properly checked with this + * function due to the variable length of the written string, if you + * need precise control over partial write failures, you need to + * create you own printf()-like wrapper around g_output_stream_write() + * or g_output_stream_write_all(). + * + * Since: 2.40 + * Returns: %TRUE on success, %FALSE if there was an error + */ + + +/** * g_output_stream_write: (virtual write_fn) * @stream: a #GOutputStream. * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. @@ -29429,7 +29489,7 @@ /** * g_settings_get_default_value: * @settings: a #GSettings object - * @key: the key to check for being set + * @key: the key to get the default value for * * Gets the "default value" of a key. * @@ -29657,7 +29717,7 @@ /** * g_settings_get_user_value: * @settings: a #GSettings object - * @key: the key to check for being set + * @key: the key to get the user value for * * Checks the "user value" of a key, if there is one. * @@ -29773,7 +29833,10 @@ * schemas that are available. The list must not be modified or * freed. * Since: 2.26 - * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead + * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead. + * If you used g_settings_list_schemas() to check for the presence of + * a particular schema, use g_settings_schema_source_lookup() instead + * of your whole loop. */ @@ -32155,6 +32218,13 @@ * * Try to get the remote address of a socket connection. * + * Since GLib 2.40, when used with g_socket_client_connect() or + * g_socket_client_connect_async(), during emission of + * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote + * address that will be used for the connection. This allows + * applications to print e.g. "Connecting to example.com + * (10.42.77.3)...". + * * Returns: (transfer full): a #GSocketAddress or %NULL on error. * Free the returned object with g_object_unref(). * Since: 2.22 @@ -33633,7 +33703,7 @@ /** * g_subprocess_communicate: * @subprocess: a #GSubprocess - * @stdin_buf: data to send to the stdin of the subprocess, or %NULL + * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL * @cancellable: a #GCancellable * @stdout_buf: (out): data read from the subprocess stdout * @stderr_buf: (out): data read from the subprocess stderr @@ -33642,7 +33712,7 @@ * Communicate with the subprocess until it terminates, and all input * and output has been completed. * - * If @stdin is given, the subprocess must have been created with + * If @stdin_buf is given, the subprocess must have been created with * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the * stdin of the subprocess and the pipe is closed (ie: EOF). * @@ -33689,8 +33759,8 @@ /** * g_subprocess_communicate_async: * @subprocess: Self - * @stdin_buf: Input data - * @cancellable: Cancellable + * @stdin_buf: (allow-none): Input data, or %NULL + * @cancellable: (allow-none): Cancellable * @callback: Callback * @user_data: User data * @@ -33714,7 +33784,7 @@ /** * g_subprocess_communicate_utf8: * @subprocess: a #GSubprocess - * @stdin_buf: data to send to the stdin of the subprocess, or %NULL + * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL * @cancellable: a #GCancellable * @stdout_buf: (out): data read from the subprocess stdout * @stderr_buf: (out): data read from the subprocess stderr @@ -33728,7 +33798,7 @@ /** * g_subprocess_communicate_utf8_async: * @subprocess: Self - * @stdin_buf: Input data + * @stdin_buf: (allow-none): Input data, or %NULL * @cancellable: Cancellable * @callback: Callback * @user_data: User data @@ -33785,6 +33855,15 @@ /** + * g_subprocess_get_identifier: + * @subprocess: a #GSubprocess + * + * On UNIX, returns the process ID as a decimal string. On Windows, + * returns the result of GetProcessId() also as a string. + */ + + +/** * g_subprocess_get_if_exited: * @subprocess: a #GSubprocess * diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 69981bdf..c0c7febf 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -1257,7 +1257,7 @@ * and g_return_val_if_fail(). * @G_LOG_LEVEL_WARNING: log level for warnings, see g_warning() * @G_LOG_LEVEL_MESSAGE: log level for messages, see g_message() - * @G_LOG_LEVEL_INFO: log level for informational messages + * @G_LOG_LEVEL_INFO: log level for informational messages, see g_info() * @G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug() * @G_LOG_LEVEL_MASK: a mask including all log levels * @@ -4274,14 +4274,6 @@ /** - * G_OS_BEOS: - * - * This macro is defined only on BeOS. So you can bracket - * BeOS-specific code in "#ifdef G_OS_BEOS". - */ - - -/** * G_OS_UNIX: * * This macro is defined only on UNIX. So you can bracket @@ -8551,7 +8543,7 @@ * Converts a #gdouble to a string, using the '.' as * decimal point. * - * This functions generates enough precision that converting + * This function generates enough precision that converting * the string back using g_ascii_strtod() gives the same machine-number * (on machines with IEEE compatible 64bit doubles). It is * guaranteed that the size of the resulting string will never @@ -8785,6 +8777,8 @@ * characters include all ASCII letters. If you compare two CP932 * strings using this function, you will get false matches. * + * Both @s1 and @s2 must be non-%NULL. + * * Returns: 0 if the strings match, a negative value if @s1 < @s2, * or a positive value if @s1 > @s2. */ @@ -9153,6 +9147,22 @@ /** + * g_assert_nonnull: + * @expr: the expression to check + * + * Debugging macro to check an expression is not %NULL. + * + * If the assertion fails (i.e. the expression is %NULL), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.40 + */ + + +/** * g_assert_not_reached: * * Debugging macro to terminate the application if it is ever @@ -14123,6 +14133,9 @@ * character will automatically be appended to @..., and need not be entered * manually. * + * Such messages are suppressed by the g_log_default_handler() unless + * the G_MESSAGES_DEBUG environment variable is set appropriately. + * * Since: 2.6 */ @@ -15579,6 +15592,7 @@ * corresponding value it is able to be stored more efficiently. See * the discussion in the section description. * + * Returns: %TRUE if the key did not exist yet * Since: 2.32 */ @@ -15767,6 +15781,8 @@ * value is freed using that function. If you supplied a * @key_destroy_func when creating the #GHashTable, the passed * key is freed using that function. + * + * Returns: %TRUE if the key did not exist yet */ @@ -16001,6 +16017,8 @@ * the #GHashTable, the old value is freed using that function. * If you supplied a @key_destroy_func when creating the * #GHashTable, the old key is freed using that function. + * + * Returns: %TRUE of the key did not exist yet */ @@ -16680,6 +16698,24 @@ /** + * g_info: + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) + * + * A convenience function/macro to log an informational message. Seldom used. + * + * If g_log_default_handler() is used as the log handler function, a new-line + * character will automatically be appended to @..., and need not be entered + * manually. + * + * Such messages are suppressed by the g_log_default_handler() unless + * the G_MESSAGES_DEBUG environment variable is set appropriately. + * + * Since: 2.40 + */ + + +/** * g_int64_equal: * @v1: a pointer to a #gint64 key * @v2: a pointer to a #gint64 key to compare with @v1 @@ -17847,7 +17883,7 @@ * g_key_file_load_from_data: * @key_file: an empty #GKeyFile struct * @data: key file loaded in memory - * @length: the length of @data in bytes (or -1 if data is nul-terminated) + * @length: the length of @data in bytes (or (gsize)-1 if data is nul-terminated) * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * @@ -20658,10 +20694,7 @@ * Copies a block of memory @len bytes long, from @src to @dest. * The source and destination areas may overlap. * - * In order to use this function, you must include - * <filename>string.h</filename> yourself, because this macro will - * typically simply resolve to memmove() and GLib does not include - * <filename>string.h</filename> for you. + * Deprecated: 2.40: Just use memmove(). */ @@ -22440,15 +22473,16 @@ /** * g_ptr_array_remove_range: - * @array: a @GPtrArray. - * @index_: the index of the first pointer to remove. - * @length: the number of pointers to remove. + * @array: a @GPtrArray + * @index_: the index of the first pointer to remove + * @length: the number of pointers to remove * * Removes the given number of pointers starting at the given index * from a #GPtrArray. The following elements are moved to close the * gap. If @array has a non-%NULL #GDestroyNotify function it is called * for the removed elements. * + * Returns: the @array * Since: 2.4 */ @@ -28795,7 +28829,9 @@ * Changed if any arguments were handled. * @argv: Address of the @argv parameter of main(). * Any parameters understood by g_test_init() stripped before return. - * @...: Reserved for future extension. Currently, you must pass %NULL. + * @...: %NULL-terminated list of special options. Currently the only + * defined option is <literal>"no_g_set_prgname"</literal>, which + * will cause g_test_init() to not call g_set_prgname(). * * Initialize the GLib testing framework, e.g. by seeding the * test random number generator, the name for g_get_prgname() @@ -29169,7 +29205,9 @@ * g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(), * g_assert_error(), g_test_assert_expected_messages() and the various * g_test_trap_assert_*() macros to not abort to program, but instead - * call g_test_fail() and continue. + * call g_test_fail() and continue. (This also changes the behavior of + * g_test_fail() so that it will not cause the test program to abort + * after completing the failed test.) * * Note that the g_assert_not_reached() and g_assert() are not * affected by this. @@ -32344,7 +32382,7 @@ /** - * g_variant_builder_add: (skp) + * g_variant_builder_add: (skip) * @builder: a #GVariantBuilder * @format_string: a #GVariant varargs format string * @...: arguments, as per @format_string @@ -32356,25 +32394,25 @@ * * This function might be used as follows: * - * <programlisting> + * |[ * GVariant * * make_pointless_dictionary (void) * { - * GVariantBuilder *builder; + * GVariantBuilder builder; * int i; * - * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY); + * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); * for (i = 0; i < 16; i++) * { * gchar buf[3]; * * sprintf (buf, "%d", i); - * g_variant_builder_add (builder, "{is}", i, buf); + * g_variant_builder_add (&builder, "{is}", i, buf); * } * - * return g_variant_builder_end (builder); + * return g_variant_builder_end (&builder); * } - * </programlisting> + * ]| * * Since: 2.24 */ @@ -32394,20 +32432,20 @@ * * This function might be used as follows: * - * <programlisting> + * |[ * GVariant * * make_pointless_dictionary (void) * { - * GVariantBuilder *builder; + * GVariantBuilder builder; * int i; * - * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY); - * g_variant_builder_add_parsed (builder, "{'width', <%i>}", 600); - * g_variant_builder_add_parsed (builder, "{'title', <%s>}", "foo"); - * g_variant_builder_add_parsed (builder, "{'transparency', <0.5>}"); - * return g_variant_builder_end (builder); + * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); + * g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); + * g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); + * g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); + * return g_variant_builder_end (&builder); * } - * </programlisting> + * ]| * * Since: 2.26 */ diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c index 0b40df3e..ccfbccaa 100644 --- a/gir/gmodule-2.0.c +++ b/gir/gmodule-2.0.c @@ -74,8 +74,8 @@ * G_MODULE_SUFFIX: * * Expands to the proper shared library suffix for the current platform - * without the leading dot. For the most Unices and Linux this is "so", - * for some HP-UX versions this is "sl" and for Windows this is "dll". + * without the leading dot. For most Unices and Linux this is "so", and + * for Windows this is "dll". */ @@ -87,7 +87,7 @@ * These functions provide a portable way to dynamically load object files * (commonly known as 'plug-ins'). The current implementation supports all * systems that provide an implementation of dlopen() (e.g. Linux/Sun), as - * well as HP-UX via its shl_load() mechanism, and Windows platforms via DLLs. + * well as Windows platforms via DLLs. * * A program which wants to use these functions must be linked to the * libraries output by the command diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 2a0d2767..89c083cb 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -1558,7 +1558,7 @@ /** * g_enum_complete_type_info: * @g_enum_type: the type identifier of the type being completed - * @info: the #GTypeInfo struct to be filled in + * @info: (out callee-allocates): the #GTypeInfo struct to be filled in * @const_values: An array of #GEnumValue structs for the possible * enumeration values. The array is terminated by a struct with all * members being 0. @@ -1593,8 +1593,8 @@ * * Returns the #GEnumValue for a value. * - * Returns: the #GEnumValue for @value, or %NULL if @value is not a - * member of the enumeration + * Returns: (transfer none): the #GEnumValue for @value, or %NULL + * if @value is not a member of the enumeration */ @@ -1605,8 +1605,9 @@ * * Looks up a #GEnumValue by name. * - * Returns: the #GEnumValue with name @name, or %NULL if the - * enumeration doesn't have a member with that name + * Returns: (transfer none): the #GEnumValue with name @name, + * or %NULL if the enumeration doesn't have a member + * with that name */ @@ -1617,8 +1618,9 @@ * * Looks up a #GEnumValue by nickname. * - * Returns: the #GEnumValue with nickname @nick, or %NULL if the - * enumeration doesn't have a member with that nickname + * Returns: (transfer none): the #GEnumValue with nickname @nick, + * or %NULL if the enumeration doesn't have a member + * with that nickname */ @@ -1644,7 +1646,7 @@ /** * g_flags_complete_type_info: * @g_flags_type: the type identifier of the type being completed - * @info: the #GTypeInfo struct to be filled in + * @info: (out callee-allocates): the #GTypeInfo struct to be filled in * @const_values: An array of #GFlagsValue structs for the possible * enumeration values. The array is terminated by a struct with all * members being 0. @@ -1662,8 +1664,8 @@ * * Returns the first #GFlagsValue which is set in @value. * - * Returns: the first #GFlagsValue which is set in @value, or %NULL if - * none is set + * Returns: (transfer none): the first #GFlagsValue which is set in + * @value, or %NULL if none is set */ @@ -1674,8 +1676,8 @@ * * Looks up a #GFlagsValue by name. * - * Returns: the #GFlagsValue with name @name, or %NULL if there is no - * flag with that name + * Returns: (transfer none): the #GFlagsValue with name @name, + * or %NULL if there is no flag with that name */ @@ -1686,8 +1688,8 @@ * * Looks up a #GFlagsValue by nickname. * - * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is - * no flag with that nickname + * Returns: (transfer none): the #GFlagsValue with nickname @nick, + * or %NULL if there is no flag with that nickname */ @@ -2438,6 +2440,11 @@ * When possible, eg. when signaling a property change from within the class * that registered the property, you should use g_object_notify_by_pspec() * instead. + * + * Note that emission of the notify signal may be blocked with + * g_object_freeze_notify(). In this case, the signal emissions are queued + * and will be emitted (in reverse order) when g_object_thaw_notify() is + * called. */ @@ -2621,6 +2628,10 @@ * name/value pairs, followed by %NULL * * Sets properties on an object. + * + * Note that the "notify" signals are queued and only emitted (in + * reverse order) after all properties have been set. See + * g_object_freeze_notify(). */ @@ -2773,7 +2784,8 @@ * and when it reaches zero, queued "notify" signals are emitted. * * Duplicate notifications for each property are squashed so that at most one - * #GObject::notify signal is emitted for each property. + * #GObject::notify signal is emitted for each property, in the reverse order + * in which they have been queued. * * It is an error to call this function when the freeze count is zero. */ |