[gobject-introspection] Update annotations from glib git d51e0615f9a6c1aa1898c46f2cf3135ca5ccd463

From: Colin Walters <walters src gnome org>
To: commits-list gnome org
Cc:
Subject: [gobject-introspection] Update annotations from glib git d51e0615f9a6c1aa1898c46f2cf3135ca5ccd463
Date: Mon, 22 Aug 2011 18:29:29 +0000 (UTC)
commit 86f15bd103a2781707969edc21aa6973822d09fb
Author: Colin Walters <walters verbum org>
Date:   Mon Aug 22 14:28:03 2011 -0400

    Update annotations from glib git d51e0615f9a6c1aa1898c46f2cf3135ca5ccd463

 gir/gio-2.0.c     |   77 +++++----------------------------------------
 gir/glib-2.0.c    |   89 +++++++++++++++++++++++++++++------------------------
 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 fc64624..4722914 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 dba09c2..ac7fc91 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 974afab..d96bc46 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.
  *
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]