From 86a4ae8ede108284832300e278a3186b9152ff9d Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Mon, 20 Aug 2012 12:33:33 -0400 Subject: [PATCH] Update annotations from glib git --- gir/gio-2.0.c | 121 +++++++++++++++++++++++++------- gir/glib-2.0.c | 212 +++++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 259 insertions(+), 74 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 13174ac..371155b 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -2483,21 +2483,33 @@ /** * GTlsCertificate:certificate: * - * The DER (binary) encoded representation of the certificate's - * public key. This property and the - * #GTlsCertificate:certificate-pem property represent the same - * data, just in different forms. + * The DER (binary) encoded representation of the certificate. + * This property and the #GTlsCertificate:certificate-bytes contain + * the same data. The #GTlsCertificate:certificate-pem property + * represents the same data, just in different forms. * * Since: 2.28 */ /** + * GTlsCertificate:certificate-bytes: + * + * The DER (binary) encoded representation of the certificate as + * a #GBytes. The #GTlsCertificate:certificate property contains + * the same data. The #GTlsCertificate:certificate-pem property + * contains the same data as this property in a different form. + * + * Since: 2.34 + */ + + +/** * GTlsCertificate:certificate-pem: * - * The PEM (ASCII) encoded representation of the certificate's - * public key. This property and the #GTlsCertificate:certificate - * property represent the same data, just in different forms. + * The PEM (ASCII) encoded representation of the certificate. + * The #GTlsCertificate:certificate and #GTlsCertificate:certificate-bytes + * properties represent the same data, just in a different form. * * Since: 2.28 */ @@ -2533,6 +2545,17 @@ /** + * GTlsCertificate:private-key-bytes: + * + * The DER (binary) encoded representation of the certificate's + * private key. This property and the #GtlsCertificate:private-key + * property contain the same data. + * + * Since: 2.34 + */ + + +/** * GTlsCertificate:private-key-pem: * * The PEM (ASCII) encoded representation of the certificate's @@ -3119,7 +3142,7 @@ * * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name - * and modification time from the file info to the the GZIP header. + * and modification time from the file info to the GZIP header. * * Since: 2.26 */ @@ -4171,6 +4194,7 @@ * FOO_BAR_ERROR_FAILED, * FOO_BAR_ERROR_ANOTHER_ERROR, * FOO_BAR_ERROR_SOME_THIRD_ERROR, + * FOO_BAR_N_ERRORS /*< skip >*/ * } FooBarError; * * /* foo-bar-error.c: */ @@ -4182,6 +4206,9 @@ * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, * }; * + * /* Ensure that every error code has an associated D-Bus error name */ + * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); + * * GQuark * foo_bar_error_quark (void) * { @@ -4190,7 +4217,6 @@ * &quark_volatile, * foo_bar_error_entries, * G_N_ELEMENTS (foo_bar_error_entries)); - * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) - 1 == FOO_BAR_ERROR_SOME_THIRD_ERROR); * return (GQuark) quark_volatile; * } * @@ -5624,7 +5650,7 @@ * @include: gio/gio.h * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased * - * #GPollableInputStream is implemented by #GInputStreams that + * #GPollableInputStream is implemented by #GInputStreams that * can be polled for readiness to read. This can be used when * interfacing with a non-GIO API that expects * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. @@ -5639,7 +5665,7 @@ * @include: gio/gio.h * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream * - * #GPollableOutputStream is implemented by #GOutputStreams that + * #GPollableOutputStream is implemented by #GOutputStreams that * can be polled for readiness to write. This can be used when * interfacing with a non-GIO API that expects * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. @@ -6073,7 +6099,7 @@ /** * SECTION:gsettingsschema - * @short_description: introspecting and controlling the loading of #GSettings schemas + * @short_description: introspecting and controlling the loading of GSettings schemas * * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a * mechanism for advanced control over the loading of schemas and a @@ -6800,9 +6826,9 @@ * @see_also: #GTlsConnection * * A certificate used for TLS authentication and encryption. - * This can represent either a public key only (eg, the certificate + * This can represent either a certificate only (eg, the certificate * received by a client from a server), or the combination of - * a public key and a private key (which is needed when acting as a + * a certificate and a private key (which is needed when acting as a * #GTlsServerConnection). * * Since: 2.28 @@ -17538,7 +17564,7 @@ * @error: a #GError, or %NULL * * Deletes a file. If the @file is a directory, it will only be deleted if it - * is empty. + * is empty. This has the same semantics as g_unlink(). * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation @@ -17550,6 +17576,37 @@ /** + * g_file_delete_async: + * @file: input #GFile. + * @io_priority: the I/O priority of the request + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously delete a file. If the @file is a directory, it will + * only be deleted if it is empty. This has the same semantics as + * g_unlink(). + * + * Virtual: delete_file_async + * Since: 2.34 + */ + + +/** + * g_file_delete_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError, or %NULL + * + * Finishes deleting a file started with + * g_file_delete_async(). + * + * Virtual: delete_file_finish + * Since: 2.34 + */ + + +/** * g_file_descriptor_based_get_fd: * @fd_based: a #GFileDescriptorBased. * @@ -25042,7 +25099,7 @@ * @inetaddr: The proxy server #GInetAddress. * @port: The proxy server port. * @protocol: The proxy protocol to support, in lower case (e.g. socks, http). - * @dest_hostname: The destination hostname the the proxy should tunnel to. + * @dest_hostname: The destination hostname the proxy should tunnel to. * @dest_port: The destination port to tunnel to. * @username: (allow-none): The username to authenticate to the proxy server (or %NULL). * @password: (allow-none): The password to authenticate to the proxy server (or %NULL). @@ -25742,7 +25799,7 @@ * @error: return location for a #GError, or %NULL * * Returns all the names of children at the specified @path in the set of - * globally registred resources. + * globally registered resources. * The return result is a %NULL terminated list of strings which should * be released with g_strfreev(). * @@ -25762,7 +25819,7 @@ * @error: return location for a #GError, or %NULL * * Looks for a file at the specified @path in the set of - * globally registred resources and if found returns information about it. + * globally registered resources and if found returns information about it. * * @lookup_flags controls the behaviour of the lookup. * @@ -25778,7 +25835,7 @@ * @error: return location for a #GError, or %NULL * * Looks for a file at the specified @path in the set of - * globally registred resources and returns a #GBytes that + * globally registered resources and returns a #GBytes that * lets you directly access the data in memory. * * The data is always followed by a zero byte, so you @@ -25804,7 +25861,7 @@ * @error: return location for a #GError, or %NULL * * Looks for a file at the specified @path in the set of - * globally registred resources and returns a #GInputStream + * globally registered resources and returns a #GInputStream * that lets you read the data. * * @lookup_flags controls the behaviour of the lookup. @@ -26882,7 +26939,7 @@ * source, the lookup will recurse to the parent. * * Second, any references to other schemas specified within this - * source (ie: child or extents) + * source (ie: child or extends) * references may be resolved from the @parent. * * For this second reason, except in very unusual situations, the @@ -28847,7 +28904,7 @@ * @socket: a #GSocket. * * Returns the underlying OS socket object. On unix this - * is a socket file descriptor, and on windows this is + * is a socket file descriptor, and on Windows this is * a Winsock2 SOCKET handle. This may be useful for * doing platform specific or otherwise unusual operations * on the socket. @@ -29988,7 +30045,7 @@ * g_static_resource_get_resource: * @static_resource: pointer to a static #GStaticResource * - * Gets the GResource that was registred by a call to g_static_resource_init(). + * Gets the GResource that was registered by a call to g_static_resource_init(). * * This is normally used by code generated by * glib-compile-resources @@ -30347,6 +30404,22 @@ /** + * g_tls_certificate_is_same: + * @cert_one: first certificate to compare + * @cert_two: second certificate to compare + * + * Check if two #GTlsCertificate objects represent the same certificate. + * The raw DER byte data of the two certificates are checked for equality. + * This has the effect that two certificates may compare equal even if + * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or + * #GTlsCertificate:private-key-pem properties differ. + * + * Returns: whether the same or not + * Since: 2.34 + */ + + +/** * g_tls_certificate_list_new_from_file: * @file: file containing PEM-encoded certificates to import * @error: #GError for error reporting, or %NULL to ignore. @@ -32266,7 +32339,7 @@ /** * g_unix_socket_address_abstract_names_supported: * - * Checks if abstract unix domain socket names are supported. + * Checks if abstract UNIX domain socket names are supported. * * Returns: %TRUE if supported, %FALSE otherwise * Since: 2.22 diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 7942c84..ec62711 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -1157,7 +1157,7 @@ * @G_MARKUP_COLLECT_OPTIONAL: can be bitwise ORed with the other fields. If present, allows the attribute not to appear. A default value is set depending on what value type is used * * A mixed enumerated type and flags field. You must specify one type - * (string, strdup, boolean, tristate). Additionally, you may optionally + * (string, strdup, boolean, tristate). Additionally, you may optionally * bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL. * * It is likely that this enum will be extended in the future to @@ -2702,7 +2702,11 @@ * if the compiler is a new enough gcc. This attribute * tells the compiler that the function returns a pointer to memory of a * size that is specified by the @xth function parameter. - * See the GNU C documentation for details. + * + * Place the attribute after the function declaration, just before the + * semicolon. + * + * See the GNU C documentation for more details. * * Since: 2.18 */ @@ -2717,7 +2721,11 @@ * if the compiler is a new enough gcc. This attribute * tells the compiler that the function returns a pointer to memory of a * size that is specified by the product of two function parameters. - * See the GNU C documentation for details. + * + * Place the attribute after the function declaration, just before the + * semicolon. + * + * See the GNU C documentation for more details. * * Since: 2.18 */ @@ -2751,7 +2759,11 @@ * the compiler is gcc. Declaring a function as const * enables better optimization of calls to the function. A const function * doesn't examine any values except its parameters, and has no effects - * except its return value. See the GNU C documentation for details. + * except its return value. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. * * * A function that has pointer arguments and examines the data pointed to @@ -2770,7 +2782,10 @@ * variables and functions as deprecated. When called with the * option, the compiler will * generate warnings when deprecated interfaces are used. - * See the GNU C documentation for details. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. * * Since: 2.2 */ @@ -2783,7 +2798,10 @@ * Like %G_GNUC_DEPRECATED, but names the intended replacement for the * deprecated symbol if the version of gcc in use is * new enough to support custom deprecation messages. - * See the GNU C documentation for details. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. * * Note that if @f is a macro, it will be expanded in the warning message. * You can enclose it in quotes to prevent this. (The quotes will show up @@ -2828,7 +2846,12 @@ * so that the result can be passed to a printf(), scanf(), strftime() * or strfmon() style function (with the remaining arguments to the * format function the same as they would have been for the unmodified - * string). See the GNU C documentation for details. + * string). + * + * Place the attribute after the function declaration, just after the + * semicolon. + * + * See the GNU C documentation for more details. * * |[ * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); @@ -2884,7 +2907,11 @@ * better optimization of the function. A function can have the malloc * attribute if it returns a pointer which is guaranteed to not alias with * any other pointer when the function returns (in practice, this means newly - * allocated memory). See the GNU C documentation for details. + * allocated memory). + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. * * Since: 2.6 */ @@ -2909,8 +2936,11 @@ * Expands to the GNU C noreturn function attribute * if the compiler is gcc. It is used for declaring * functions which never return. It enables optimization of the function, - * and avoids possible compiler warnings. See the GNU C documentation for - * details. + * and avoids possible compiler warnings. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. */ @@ -2921,7 +2951,10 @@ * attribute if the compiler is gcc. Functions with this * attribute will not be instrumented for profiling, when the compiler is * called with the option. - * See the GNU C documentation for details. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. */ @@ -2932,7 +2965,11 @@ * if the compiler is gcc, or "" if it isn't. This * function attribute only applies to variadic functions and instructs * the compiler to check that the argument list is terminated with an - * explicit %NULL. See the GNU C documentation for details. + * explicit %NULL. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. * * Since: 2.8 */ @@ -2958,7 +2995,12 @@ * if the compiler is gcc. This is used for declaring * functions which take a variable number of arguments, with the same * syntax as printf(). It allows the compiler to type-check the arguments - * passed to the function. See the GNU C documentation for details. + * passed to the function. + * + * Place the attribute after the function declaration, just before the + * semicolon. + * + * See the GNU C documentation for more details. * * |[ * gint g_snprintf (gchar *string, @@ -2976,8 +3018,11 @@ * compiler is gcc. Declaring a function as pure enables * better optimization of calls to the function. A pure function has no * effects except its return value and the return value depends only on - * the parameters and/or global variables. See the GNU C documentation - * for details. + * the parameters and/or global variables. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. */ @@ -2999,8 +3044,19 @@ * * Expands to the GNU C unused function attribute if * the compiler is gcc. It is used for declaring - * functions which may never be used. It avoids possible compiler warnings. - * See the GNU C documentation for details. + * functions and arguments which may never be used. It avoids possible compiler + * warnings. + * + * For functions, place the attribute after the declaration, just before the + * semicolon. For arguments, place the attribute at the beginning of the + * argument declaration. + * + * |[ + * void my_unused_function (G_GNUC_UNUSED gint unused_argument, + * gint other_argument) G_GNUC_UNUSED; + * ]| + * + * See the GNU C documentation for more details. */ @@ -3010,7 +3066,11 @@ * Expands to the GNU C warn_unused_result function * attribute if the compiler is gcc, or "" if it isn't. * This function attribute makes the compiler emit a warning if the result - * of a function call is ignored. See the GNU C documentation for details. + * of a function call is ignored. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. * * Since: 2.10 */ @@ -11160,6 +11220,22 @@ /** + * g_compute_checksum_for_bytes: + * @checksum_type: a #GChecksumType + * @data: binary blob to compute the digest of + * + * Computes the checksum for a binary @data. This is a + * convenience wrapper for g_checksum_new(), g_checksum_get_string() + * and g_checksum_free(). + * + * The hexadecimal string returned will be in lower case. + * + * Returns: the digest of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it. + * Since: 2.34 + */ + + +/** * g_compute_checksum_for_data: * @checksum_type: a #GChecksumType * @data: binary blob to compute the digest of @@ -16899,7 +16975,7 @@ /** * g_key_file_load_from_data: * @key_file: an empty #GKeyFile struct - * @data: (array length=length): key file loaded in memory + * @data: key file loaded in memory * @length: the length of @data in bytes (or -1 if data is nul-terminated) * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL @@ -18208,7 +18284,7 @@ * given moment without further waiting. * * Note that even when @may_block is %TRUE, it is still possible for - * g_main_context_iteration() to return %FALSE, since the the wait may + * g_main_context_iteration() to return %FALSE, since the wait may * be interrupted for other reasons than an event source becoming ready. * * Returns: %TRUE if events were dispatched. @@ -18665,6 +18741,19 @@ /** + * g_mapped_file_get_bytes: + * @file: a #GMappedFile + * + * Creates a new #GBytes which references the data mapped from @file. + * The mapped contents of the file must not be modified after creating this + * bytes object, because a #GBytes should be immutable. + * + * Returns: (transfer full): A newly allocated #GBytes referencing data from @file + * Since: 2.34 + */ + + +/** * g_mapped_file_get_contents: * @file: a #GMappedFile * @@ -18816,6 +18905,34 @@ /** + * g_markup_collect_known_attributes: + * @element_name: the current tag name + * @attribute_names: (array zero-terminated=1): the attribute names + * @attribute_values: (array zero-terminated=1): the attribute values + * @error: (allow-none): a pointer to a #GError or %NULL + * @first_type: the #GMarkupCollectType of the first attribute + * @first_attr: the name of the first attribute + * @...: a pointer to the storage location of the first attribute (or %NULL), followed by more types names and pointers, ending with %G_MARKUP_COLLECT_INVALID + * + * Collects the attributes of the element from the data passed to the + * #GMarkupParser start_element function, dealing with common error + * conditions and supporting boolean values. + * + * This is a more relaxed version of g_markup_collect_attributes(), which + * ignores attributes found in @attribute_names but not listed in @first_attr + * or @...; by comparison g_markup_collect_attributes() will return + * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE instead. Otherwise, this function behaves + * identically. + * + * This is intended for situations where the markup being parsed may use + * extensions in other namespaces and thus contain extra, unknown, attributes. + * + * Returns: %TRUE if successful + * Since: 2.34 + */ + + +/** * g_markup_escape_text: * @text: some valid UTF-8 text * @length: length of @text in bytes, or -1 if the text is nul-terminated @@ -24867,7 +24984,13 @@ * @source: a #GSource * * Gets the #GMainContext with which the source is associated. - * Calling this function on a destroyed source is an error. + * + * You can call this on a source that has been destroyed, provided + * that the #GMainContext it was attached to still exists (in which + * case it will return that #GMainContext). In particular, you can + * always call this function on the source returned from + * g_main_current_source(). But calling this function on a source + * whose #GMainContext has been destroyed is an error. * * Returns: (transfer none) (allow-none): the #GMainContext with which the source is associated, or %NULL if the context has not yet been added to a source. */ @@ -27019,57 +27142,57 @@ * * * - * list test cases available in a test executable. + * List test cases available in a test executable. * * * * * - * provide a random seed to reproduce test runs using random numbers. + * Provide a random seed to reproduce test runs using random numbers. * * * * - * run tests verbosely. + * Run tests verbosely. * * * , - * run tests quietly. + * Run tests quietly. * * * * - * execute all tests matching TESTPATH. + * Execute all tests matching TESTPATH. * * * * * - * execute tests according to these test modes: + * Execute tests according to these test modes: * * * perf * - * performance tests, may take long and report results. + * Performance tests, may take long and report results. * * * * slow, thorough * - * slow and thorough tests, may take quite long and + * Slow and thorough tests, may take quite long and * maximize coverage. * * * * quick * - * quick tests, should run really quickly and give good coverage. + * Quick tests, should run really quickly and give good coverage. * * * * undefined * - * tests for undefined behaviour, may provoke programming errors + * Tests for undefined behaviour, may provoke programming errors * under g_test_trap_fork() to check that appropriate assertions * or warnings are given * @@ -27077,7 +27200,7 @@ * * no-undefined * - * avoid tests for undefined behaviour + * Avoid tests for undefined behaviour * * * @@ -27085,19 +27208,7 @@ * * * - * debug test logging output. - * - * - * , - * gtester-specific argument. - * - * - * - * gtester-specific argument. - * - * - * - * gtester-specific argument. + * Debug test logging output. * * * @@ -27826,8 +27937,7 @@ * * By setting @interval to 0, idle threads will not be stopped. * - * This function makes use of g_async_queue_timed_pop () using - * @interval. + * The default value is 15000 (15 seconds). * * Since: 2.10 */ @@ -27871,6 +27981,8 @@ * Sets the maximal number of unused threads to @max_threads. * If @max_threads is -1, no limit is imposed on the number * of unused threads. + * + * The default value is 2. */ @@ -32594,7 +32706,7 @@ /** - * g_variant_type_new_array: + * g_variant_type_new_array: (constructor) * @element: a #GVariantType * * Constructs the type corresponding to an array of elements of the @@ -32607,7 +32719,7 @@ /** - * g_variant_type_new_dict_entry: + * g_variant_type_new_dict_entry: (constructor) * @key: a basic #GVariantType * @value: a #GVariantType * @@ -32621,7 +32733,7 @@ /** - * g_variant_type_new_maybe: + * g_variant_type_new_maybe: (constructor) * @element: a #GVariantType * * Constructs the type corresponding to a maybe instance containing -- 2.7.4