diff options
author | Colin Walters <walters@verbum.org> | 2011-08-22 14:28:03 -0400 |
---|---|---|
committer | Colin Walters <walters@verbum.org> | 2011-08-22 14:28:03 -0400 |
commit | 86f15bd103a2781707969edc21aa6973822d09fb (patch) | |
tree | f1adf5b3eff481c1d37ccb0f2bd32467bf0f7090 /gir | |
parent | 92c320e422645966956a4ba1f7cc2f6684f69a58 (diff) | |
download | gobject-introspection-86f15bd103a2781707969edc21aa6973822d09fb.tar.gz |
Update annotations from glib git d51e0615f9a6c1aa1898c46f2cf3135ca5ccd463
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 77 | ||||
-rw-r--r-- | gir/glib-2.0.c | 89 | ||||
-rw-r--r-- | gir/gobject-2.0.c | 50 |
3 files changed, 83 insertions, 133 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index fc646242..47229144 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -897,11 +897,11 @@ /** * GClosureMarshal: * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. + * @return_value: (allow-none): a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. * @n_param_values: the length of the @param_values array - * @param_values: an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() + * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure + * @invocation_hint: (allow-none): the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: (allow-none): additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() * * The type used for marshaller functions. */ @@ -5344,7 +5344,7 @@ * GSignalEmissionHook: * @ihint: Signal invocation hint, see #GSignalInvocationHint. * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted. - * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission. + * @param_values: (array length=n_param_values): the instance on which the signal was emitted, followed by the parameters of the emission. * @data: user data associated with the hook. * * A simple function pointer to get invoked when the signal is emitted. This @@ -6050,30 +6050,6 @@ /** - * GTimeZoneMonitor: - * - * This is an opaque structure type. - */ - - -/** - * GTimeZoneMonitor::changed: - * @monitor: the #GTimeZoneMonitor - * - * Indicates that the local timezone has changed. - * - * The g_time_zone_refresh_local() function is called just before this - * signal is emitted, so any new #GTimeZone or #GDateTime instances - * created from signal handlers will be as per the new timezone. - * - * Note that this signal is not emitted in response to entering or - * exiting daylight savings time within a given timezone. It's only - * for when the user has changed the timezone to that of a different - * location. - */ - - -/** * GTlsAuthenticationMode: * @G_TLS_AUTHENTICATION_NONE: client authentication not required * @G_TLS_AUTHENTICATION_REQUESTED: client authentication is requested @@ -14361,25 +14337,6 @@ /** - * SECTION:gtimezonemonitor - * @title: GTimeZoneMonitor - * @short_description: Monitor the local timezone - * - * #GTimeZoneMonitor is a utility class to monitor the local timezone for - * changes (ie: in response to the user manually changing the timezone - * to that of a different locale). - * - * You must use this class in order for your program to notice changes - * to the local timezone. It works by monitoring the /etc/localtime - * file. When the timezone is found to have changed, - * g_time_zone_refresh_local() is called and the "changed" signal is - * emitted on the #GTimeZoneMonitor (in that order). - * - * Windows support is not presently working. - */ - - -/** * SECTION:gtls * @title: TLS Overview * @short_description: TLS (aka SSL) support for GSocketConnection @@ -17240,7 +17197,7 @@ * and pass it to the operations. * * One #GCancellable can be used in multiple consecutive - * operations, but not in multiple concurrent operations. + * operations or in multiple concurrent operations. * * Returns: a #GCancellable. */ @@ -17293,6 +17250,9 @@ * @cancellable: a #GCancellable object. * * Resets @cancellable to its uncancelled state. + * + * If cancellable is currently in use by any cancellable operation + * then the behavior of this function is undefined. */ @@ -34368,25 +34328,6 @@ /** - * g_time_zone_monitor_get: - * - * Gets the singleton instance of the #GTimeZoneMonitor class, creating - * it if required. - * - * You should call g_object_unref() on the result when you no longer - * need it. Be aware, though, that this will not destroy the instance, - * so if you connected to the changed signal, you are required to - * disconnect from it for yourself. - * - * There is only one instance of #GTimeZoneMonitor and it dispatches its - * signals via the default #GMainContext. There is no way to create an - * instance that will dispatch signals using a different context. - * - * Returns: (transfer full): a reference to the #GTimeZoneMonitor. - */ - - -/** * g_tls_backend_get_certificate_type: * @backend: the #GTlsBackend * diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index dba09c28..ac7fc917 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -385,11 +385,11 @@ /** * GClosureMarshal: * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. + * @return_value: (allow-none): a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. * @n_param_values: the length of the @param_values array - * @param_values: an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() + * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure + * @invocation_hint: (allow-none): the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: (allow-none): additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() * * The type used for marshaller functions. */ @@ -2250,7 +2250,7 @@ * GSignalEmissionHook: * @ihint: Signal invocation hint, see #GSignalInvocationHint. * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted. - * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission. + * @param_values: (array length=n_param_values): the instance on which the signal was emitted, followed by the parameters of the emission. * @data: user data associated with the hook. * * A simple function pointer to get invoked when the signal is emitted. This @@ -12279,17 +12279,17 @@ /** * g_checksum_get_digest: - * @hmac: a #GHmac + * @checksum: a #GChecksum * @buffer: output buffer - * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest + * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest. * - * Gets the digest from @checksum as a raw binary array and places it + * Gets the digest from @checksum as a raw binary vector and places it * into @buffer. The size of the digest depends on the type of checksum. * - * Once this function has been called, the #GHmac is closed and can + * Once this function has been called, the #GChecksum is closed and can * no longer be updated with g_checksum_update(). * - * Since: 2.30 + * Since: 2.16 */ @@ -13597,6 +13597,11 @@ * a tab character * </simpara></listitem></varlistentry> * <varlistentry><term> + * <literal>%%T</literal>: + * </term><listitem><simpara> + * the time in 24-hour notation with seconds (<literal>%%H:%%M:%%S</literal>) + * </simpara></listitem></varlistentry> + * <varlistentry><term> * <literal>%%u</literal>: * </term><listitem><simpara> * the day of the week as a decimal, range 1 to 7, Monday being 1 @@ -15310,10 +15315,13 @@ * that probably involves returning the wall clock time (with at least * microsecond accuracy, subject to the limitations of the OS kernel). * - * Note that, on Windows, "limitations of the OS kernel" is a rather - * substantial statement. Depending on the configuration of the system, - * the wall clock time is updated as infrequently as 64 times a second - * (which is approximately every 16ms). + * It's important to note that POSIX %CLOCK_MONOTONIC does not count + * time spent while the machine is suspended. + * + * On Windows, "limitations of the OS kernel" is a rather substantial + * statement. Depending on the configuration of the system, the wall + * clock time is updated as infrequently as 64 times a second (which + * is approximately every 16ms). * * Returns: the monotonic time, in microseconds * Since: 2.28 @@ -16374,7 +16382,7 @@ /** * g_intern_static_string: - * @string: a static string + * @string: (allow-none): a static string * * Returns a canonical representation for @string. Interned strings can * be compared for equality by comparing the pointers, instead of using strcmp(). @@ -16388,7 +16396,7 @@ /** * g_intern_string: - * @string: a string + * @string: (allow-none): a string * * Returns a canonical representation for @string. Interned strings can * be compared for equality by comparing the pointers, instead of using strcmp(). @@ -22074,7 +22082,7 @@ /** * g_quark_from_static_string: - * @string: a string. + * @string: (allow-none): a string. * @Returns: the #GQuark identifying the string, or 0 if @string is %NULL. * * Gets the #GQuark identifying the given (static) string. If the @@ -22094,7 +22102,7 @@ /** * g_quark_from_string: - * @string: a string. + * @string: (allow-none): a string. * @Returns: the #GQuark identifying the string, or 0 if @string is %NULL. * * Gets the #GQuark identifying the given string. If the string does @@ -22114,7 +22122,7 @@ /** * g_quark_try_string: - * @string: a string. + * @string: (allow-none): a string. * @Returns: the #GQuark associated with the string, or 0 if @string is %NULL or there is no #GQuark associated with it. * * Gets the #GQuark associated with the given string, or 0 if string is @@ -28420,12 +28428,13 @@ /** * g_time_zone_new_local: * - * Creates a #GTimeZone corresponding to local time. + * Creates a #GTimeZone corresponding to local time. The local time + * zone may change between invocations to this function; for example, + * if the system administrator changes it. * * This is equivalent to calling g_time_zone_new() with the value of the * <varname>TZ</varname> environment variable (including the possibility - * of %NULL). Changes made to <varname>TZ</varname> after the first - * call to this function may or may not be noticed by future calls. + * of %NULL). * * You should release the return value by calling g_time_zone_unref() * when you are done with it. @@ -28463,24 +28472,6 @@ /** - * g_time_zone_refresh_local: - * - * Notifies #GTimeZone that the local timezone may have changed. - * - * In response, #GTimeZone will drop its cache of the local time zone. - * No existing #GTimeZone will be modified and no #GDateTime will change - * its timezone but future calls to g_time_zone_new_local() will start - * returning the new timezone. - * - * #GTimeZone does no monitoring of the local timezone on its own, which - * is why you have to call this function to notify it of the change. - * - * If you use #GTimeZoneMonitor to watch for changes then this function - * will automatically be called for you. - */ - - -/** * g_time_zone_unref: * @tz: a #GTimeZone * @@ -28517,6 +28508,9 @@ * and attaches it to the main loop context using g_source_attach(). You can * do these steps manually if you need greater control. * + * The interval given is in terms of monotonic time, not wall clock + * time. See g_get_monotonic_time(). + * * Returns: the ID (greater than 0) of the event source. */ @@ -28546,6 +28540,9 @@ * and attaches it to the main loop context using g_source_attach(). You can * do these steps manually if you need greater control. * + * The interval given in terms of monotonic time, not wall clock time. + * See g_get_monotonic_time(). + * * Returns: the ID (greater than 0) of the event source. * Rename to: g_timeout_add */ @@ -28571,6 +28568,9 @@ * of one second. If you need finer precision and have such a timeout, * you may want to use g_timeout_add() instead. * + * The interval given is in terms of monotonic time, not wall clock + * time. See g_get_monotonic_time(). + * * Returns: the ID (greater than 0) of the event source. * Since: 2.14 */ @@ -28615,6 +28615,9 @@ * using g_source_attach(). You can do these steps manually if you need * greater control. * + * The interval given is in terms of monotonic time, not wall clock + * time. See g_get_monotonic_time(). + * * Returns: the ID (greater than 0) of the event source. * Rename to: g_timeout_add_seconds * Since: 2.14 @@ -28631,6 +28634,9 @@ * and must be added to one with g_source_attach() before it will be * executed. * + * The interval given is in terms of monotonic time, not wall clock + * time. See g_get_monotonic_time(). + * * Returns: the newly-created timeout source */ @@ -28648,6 +28654,9 @@ * The scheduling granularity/accuracy of this timeout source will be * in seconds. * + * The interval given in terms of monotonic time, not wall clock time. + * See g_get_monotonic_time(). + * * Returns: the newly-created timeout source * Since: 2.14 */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 974afabc..d96bc46e 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -353,11 +353,11 @@ /** * GClosureMarshal: * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. + * @return_value: (allow-none): a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. * @n_param_values: the length of the @param_values array - * @param_values: an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() + * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure + * @invocation_hint: (allow-none): the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: (allow-none): additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() * * The type used for marshaller functions. */ @@ -1493,7 +1493,7 @@ * GSignalEmissionHook: * @ihint: Signal invocation hint, see #GSignalInvocationHint. * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted. - * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission. + * @param_values: (array length=n_param_values): the instance on which the signal was emitted, followed by the parameters of the emission. * @data: user data associated with the hook. * * A simple function pointer to get invoked when the signal is emitted. This @@ -6492,10 +6492,10 @@ /** * g_closure_invoke: * @closure: a #GClosure - * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. + * @return_value: (allow-none): a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. * @n_param_values: the length of the @param_values array * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure - * @invocation_hint: a context-dependent invocation hint + * @invocation_hint: (allow-none): a context-dependent invocation hint * * Invokes the closure, i.e. executes the callback represented by the @closure. */ @@ -8904,7 +8904,7 @@ /** * g_signal_chain_from_overridden: - * @instance_and_params: the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. + * @instance_and_params: (array) the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. * @return_value: Location for the return value. * * Calls the original class closure of a signal. This function should only @@ -9098,7 +9098,7 @@ /** * g_signal_emitv: - * @instance_and_params: argument list for the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. + * @instance_and_params: (array): argument list for the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. * @signal_id: the signal id * @detail: the detail * @return_value: Location to store the return value of the signal emission. @@ -9116,7 +9116,7 @@ * * Returns the invocation hint of the innermost signal emission of instance. * - * Returns: the invocation hint of the innermost signal emission. + * Returns: (transfer none): the invocation hint of the innermost signal emission. */ @@ -9156,7 +9156,7 @@ * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. * @signal_id: Signal the handler has to be connected to. * @detail: Signal detail the handler has to be connected to. - * @closure: The closure the handler will invoke. + * @closure: (allow-none): The closure the handler will invoke. * @func: The C closure callback of the handler (useless for non-C closures). * @data: The closure data of the handler's closure. * @@ -9220,7 +9220,7 @@ * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. - * @closure: The closure the handlers will invoke. + * @closure: (allow-none): The closure the handlers will invoke. * @func: The C closure callback of the handlers (useless for non-C closures). * @data: The closure data of the handlers' closures. * @@ -9254,7 +9254,7 @@ * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. - * @closure: The closure the handlers will invoke. + * @closure: (allow-none): The closure the handlers will invoke. * @func: The C closure callback of the handlers (useless for non-C closures). * @data: The closure data of the handlers' closures. * @@ -9289,7 +9289,7 @@ * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. - * @closure: The closure the handlers will invoke. + * @closure: (allow-none): The closure the handlers will invoke. * @func: The C closure callback of the handlers (useless for non-C closures). * @data: The closure data of the handlers' closures. * @@ -9336,7 +9336,7 @@ * created. Further information about the signals can be acquired through * g_signal_query(). * - * Returns: Newly allocated array of signal IDs. + * Returns: (array length=n_ids): Newly allocated array of signal IDs. */ @@ -9468,13 +9468,13 @@ * @signal_name: the name for the signal * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST - * @class_closure: The closure to invoke on signal emission; may be %NULL - * @accumulator: the accumulator for this signal; may be %NULL + * @class_closure: (allow-none): The closure to invoke on signal emission; may be %NULL + * @accumulator: (allow-none): the accumulator for this signal; may be %NULL * @accu_data: user data for the @accumulator * @c_marshaller: (allow-none): the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value * @n_params: the length of @param_types - * @param_types: an array of types, one for each parameter + * @param_types: (array length=n_params): an array of types, one for each parameter * * Creates a new signal. (This is usually done in the class initializer.) * @@ -9526,8 +9526,8 @@ * g_signal_parse_name: * @detailed_signal: a string of the form "signal-name::detail". * @itype: The interface/instance type that introduced "signal-name". - * @signal_id_p: Location to store the signal id. - * @detail_p: Location to store the detail quark. + * @signal_id_p: (out): Location to store the signal id. + * @detail_p: (out): Location to store the detail quark. * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail. * * Internal function to parse a signal name into its @signal_id @@ -9540,7 +9540,7 @@ /** * g_signal_query: * @signal_id: The signal id of the signal to query information for. - * @query: A user provided structure that is filled in with constant values upon success. + * @query: (out caller-allocates): A user provided structure that is filled in with constant values upon success. * * Queries the signal system for in-depth information about a * specific signal. This function will fill in a user-provided @@ -11247,7 +11247,7 @@ /** * g_value_set_static_string: * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: static string to be set + * @v_string: (allow-none): static string to be set * * Set the contents of a %G_TYPE_STRING #GValue to @v_string. * The string is assumed to be static, and is thus not duplicated @@ -11258,7 +11258,7 @@ /** * g_value_set_string: * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: caller-owned string to be duplicated for the #GValue + * @v_string: (allow-none): caller-owned string to be duplicated for the #GValue * * Set the contents of a %G_TYPE_STRING #GValue to @v_string. */ @@ -11267,7 +11267,7 @@ /** * g_value_set_string_take_ownership: * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: duplicated unowned string to be set + * @v_string: (allow-none): duplicated unowned string to be set * * This is an internal function introduced mainly for C marshallers. * @@ -11369,7 +11369,7 @@ /** * g_value_take_string: * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: string to take ownership of + * @v_string: (allow-none): string to take ownership of * * Sets the contents of a %G_TYPE_STRING #GValue to @v_string. * |