Introspect util.[ch]

Most of it is useless in non-C languages, so we (skip) it. However,
tp_simple_async_report_success_in_idle(), tp_utf8_make_valid(),
tp_escape_as_identifier() and the user-action-time functions all
seem like useful things to have.

The tp_g_value_slice_new() family confuses g-ir-scanner (which goes
looking for a TpGValueSlice type), but they're all (skip)'d anyway,
so #ifdef them out.

Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Reviewed-by: Xavier Claessens <xavier.claessens@collabora.co.uk>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=54543

3 files changed, 49 insertions, 41 deletions

diff --git a/telepathy-glib/introspection.am b/telepathy-glib/introspection.am
index 6194c8bbb..4789942ec 100644
--- a/telepathy-glib/introspection.am
+++ b/telepathy-glib/introspection.am
@@ -79,6 +79,7 @@ TelepathyGLib_0_12_gir_FILES = \
 	$(srcdir)/room-list.c $(srcdir)/room-list.h \
 	$(srcdir)/room-info.c $(srcdir)/room-info.h \
 	$(srcdir)/account-request.c $(srcdir)/account-request.h \
+	$(srcdir)/util.c $(srcdir)/util.h \
 	_gen/telepathy-enums.h _gen/telepathy-enums-gtk-doc.h \
 	_gen/telepathy-interfaces.h \
 	$(NULL)
diff --git a/telepathy-glib/util.c b/telepathy-glib/util.c
index 217cf5fa0..4d606d158 100644
--- a/telepathy-glib/util.c
+++ b/telepathy-glib/util.c
@@ -111,7 +111,7 @@
  */
 
 /**
- * tp_g_ptr_array_contains:
+ * tp_g_ptr_array_contains: (skip)
  * @haystack: The pointer array to be searched
  * @needle: The pointer to look for
  *
@@ -144,7 +144,7 @@ add_to_array (gpointer data,
 }
 
 /**
- * tp_g_ptr_array_extend:
+ * tp_g_ptr_array_extend: (skip)
  * @target: a #GPtrArray to copy items to
  * @source: a #GPtrArray to copy items from
  *
@@ -170,7 +170,7 @@ tp_g_ptr_array_extend (GPtrArray *target,
 }
 
 /**
- * tp_g_value_slice_new:
+ * tp_g_value_slice_new: (skip)
  * @type: The type desired for the new GValue
  *
  * Slice-allocate an empty #GValue. tp_g_value_slice_new_boolean() and similar
@@ -190,7 +190,7 @@ tp_g_value_slice_new (GType type)
 }
 
 /**
- * tp_g_value_slice_new_boolean:
+ * tp_g_value_slice_new_boolean: (skip)
  * @b: a boolean value
  *
  * Slice-allocate and initialize a #GValue. This function is convenient to
@@ -211,7 +211,7 @@ tp_g_value_slice_new_boolean (gboolean b)
 }
 
 /**
- * tp_g_value_slice_new_int:
+ * tp_g_value_slice_new_int: (skip)
  * @n: an integer
  *
  * Slice-allocate and initialize a #GValue. This function is convenient to
@@ -232,7 +232,7 @@ tp_g_value_slice_new_int (gint n)
 }
 
 /**
- * tp_g_value_slice_new_int64:
+ * tp_g_value_slice_new_int64: (skip)
  * @n: a 64-bit integer
  *
  * Slice-allocate and initialize a #GValue. This function is convenient to
@@ -253,7 +253,7 @@ tp_g_value_slice_new_int64 (gint64 n)
 }
 
 /**
- * tp_g_value_slice_new_byte:
+ * tp_g_value_slice_new_byte: (skip)
  * @n: an unsigned integer
  *
  * Slice-allocate and initialize a #GValue. This function is convenient to
@@ -274,7 +274,7 @@ tp_g_value_slice_new_byte (guchar n)
 }
 
 /**
- * tp_g_value_slice_new_uint:
+ * tp_g_value_slice_new_uint: (skip)
  * @n: an unsigned integer
  *
  * Slice-allocate and initialize a #GValue. This function is convenient to
@@ -295,7 +295,7 @@ tp_g_value_slice_new_uint (guint n)
 }
 
 /**
- * tp_g_value_slice_new_uint64:
+ * tp_g_value_slice_new_uint64: (skip)
  * @n: a 64-bit unsigned integer
  *
  * Slice-allocate and initialize a #GValue. This function is convenient to
@@ -316,7 +316,7 @@ tp_g_value_slice_new_uint64 (guint64 n)
 }
 
 /**
- * tp_g_value_slice_new_double:
+ * tp_g_value_slice_new_double: (skip)
  * @d: a number
  *
  * Slice-allocate and initialize a #GValue. This function is convenient to
@@ -337,7 +337,7 @@ tp_g_value_slice_new_double (double n)
 }
 
 /**
- * tp_g_value_slice_new_string:
+ * tp_g_value_slice_new_string: (skip)
  * @string: a string to be copied into the value
  *
  * Slice-allocate and initialize a #GValue. This function is convenient to
@@ -358,7 +358,7 @@ tp_g_value_slice_new_string (const gchar *string)
 }
 
 /**
- * tp_g_value_slice_new_static_string:
+ * tp_g_value_slice_new_static_string: (skip)
  * @string: a static string which must remain valid forever, to be pointed to
  *  by the value
  *
@@ -380,7 +380,7 @@ tp_g_value_slice_new_static_string (const gchar *string)
 }
 
 /**
- * tp_g_value_slice_new_take_string:
+ * tp_g_value_slice_new_take_string: (skip)
  * @string: a string which will be freed with g_free() by the returned #GValue
  *  (the caller must own it before calling this function, but no longer owns
  *  it after this function returns)
@@ -403,7 +403,7 @@ tp_g_value_slice_new_take_string (gchar *string)
 }
 
 /**
- * tp_g_value_slice_new_boxed:
+ * tp_g_value_slice_new_boxed: (skip)
  * @type: a boxed type
  * @p: a pointer of type @type, which will be copied
  *
@@ -428,7 +428,7 @@ tp_g_value_slice_new_boxed (GType type,
 }
 
 /**
- * tp_g_value_slice_new_static_boxed:
+ * tp_g_value_slice_new_static_boxed: (skip)
  * @type: a boxed type
  * @p: a pointer of type @type, which must remain valid forever
  *
@@ -453,7 +453,7 @@ tp_g_value_slice_new_static_boxed (GType type,
 }
 
 /**
- * tp_g_value_slice_new_take_boxed:
+ * tp_g_value_slice_new_take_boxed: (skip)
  * @type: a boxed type
  * @p: a pointer of type @type which will be freed with g_boxed_free() by the
  *  returned #GValue (the caller must own it before calling this function, but
@@ -480,7 +480,7 @@ tp_g_value_slice_new_take_boxed (GType type,
 }
 
 /**
- * tp_g_value_slice_free:
+ * tp_g_value_slice_free: (skip)
  * @value: A GValue which was allocated with the g_slice API
  *
  * Unset and free a slice-allocated GValue.
@@ -498,7 +498,7 @@ tp_g_value_slice_free (GValue *value)
 
 
 /**
- * tp_g_value_slice_dup:
+ * tp_g_value_slice_dup: (skip)
  * @value: A GValue
  *
  * <!-- 'Returns' says it all -->
@@ -537,7 +537,7 @@ _tp_g_hash_table_update_helper (gpointer key,
 }
 
 /**
- * tp_g_hash_table_update:
+ * tp_g_hash_table_update: (skip)
  * @target: The hash table to be updated
  * @source: The hash table to update it with (read-only)
  * @key_dup: function to duplicate a key from @source so it can be be stored
@@ -568,7 +568,7 @@ tp_g_hash_table_update (GHashTable *target,
 }
 
 /**
- * tp_str_empty:
+ * tp_str_empty: (skip)
  * @s: (type utf8) (transfer none): a string
  *
  * Return %TRUE if @s is empty, counting %NULL as empty.
@@ -580,7 +580,7 @@ tp_g_hash_table_update (GHashTable *target,
 /* no definition here - it's inlined */
 
 /**
- * tp_strdiff:
+ * tp_strdiff: (skip)
  * @left: The first string to compare (may be NULL)
  * @right: The second string to compare (may be NULL)
  *
@@ -601,7 +601,7 @@ tp_strdiff (const gchar *left, const gchar *right)
 
 
 /**
- * tp_mixin_offset_cast:
+ * tp_mixin_offset_cast: (skip)
  * @instance: A pointer to a structure
  * @offset: The offset of a structure member in bytes, which must not be 0
  *
@@ -621,7 +621,7 @@ tp_mixin_offset_cast (gpointer instance, guint offset)
 
 
 /**
- * tp_mixin_instance_get_offset:
+ * tp_mixin_instance_get_offset: (skip)
  * @instance: A pointer to a GObject-derived instance structure
  * @quark: A quark that was used to store the offset with g_type_set_qdata()
  *
@@ -658,7 +658,7 @@ tp_mixin_instance_get_offset (gpointer instance,
 
 
 /**
- * tp_mixin_class_get_offset:
+ * tp_mixin_class_get_offset: (skip)
  * @klass: A pointer to a GObjectClass-derived class structure
  * @quark: A quark that was used to store the offset with g_type_set_qdata()
  *
@@ -724,7 +724,8 @@ _esc_ident_bad (gchar c, gboolean is_first)
  * smaller allowed set. As a special case, "" is escaped to "_" (just for
  * completeness, really).
  *
- * Returns: the escaped string, which must be freed by the caller with #g_free
+ * Returns: (transfer full): the escaped string, which must be freed by
+ *  the caller with #g_free
  */
 gchar *
 tp_escape_as_identifier (const gchar *name)
@@ -784,7 +785,7 @@ tp_escape_as_identifier (const gchar *name)
 
 
 /**
- * tp_strv_contains:
+ * tp_strv_contains: (skip)
  * @strv: a NULL-terminated array of strings, or %NULL (which is treated as an
  *        empty strv)
  * @str: a non-NULL string
@@ -814,7 +815,7 @@ tp_strv_contains (const gchar * const *strv,
 }
 
 /**
- * tp_g_key_file_get_int64:
+ * tp_g_key_file_get_int64: (skip)
  * @key_file: a non-%NULL #GKeyFile
  * @group_name: a non-%NULL group name
  * @key: a non-%NULL key
@@ -862,7 +863,7 @@ tp_g_key_file_get_int64 (GKeyFile *key_file,
 }
 
 /**
- * tp_g_key_file_get_uint64:
+ * tp_g_key_file_get_uint64: (skip)
  * @key_file: a non-%NULL #GKeyFile
  * @group_name: a non-%NULL group name
  * @key: a non-%NULL key
@@ -981,7 +982,7 @@ closure_invalidated_cb (gpointer ctx_,
 }
 
 /**
- * tp_g_signal_connect_object:
+ * tp_g_signal_connect_object: (skip)
  * @instance: the instance to connect to.
  * @detailed_signal: a string of the form "signal-name::detail".
  * @c_handler: the #GCallback to connect.
@@ -1072,7 +1073,7 @@ _tp_quark_array_copy (const GQuark *quarks)
 }
 
 /**
- * tp_value_array_build:
+ * tp_value_array_build: (skip)
  * @length: The number of elements that should be in the array
  * @type: The type of the first argument.
  * @...: The value of the first item in the struct followed by a list of type,
@@ -1138,7 +1139,7 @@ tp_value_array_build (gsize length,
 }
 
 /**
- * tp_value_array_unpack:
+ * tp_value_array_unpack: (skip)
  * @array: the array to unpack
  * @len: The number of elements that should be in the array
  * @...: a list of correctly typed pointers to store the values in
@@ -1222,7 +1223,7 @@ struct _TpWeakRef {
 };
 
 /**
- * tp_weak_ref_new:
+ * tp_weak_ref_new: (skip)
  * @object: (type GObject.Object): an object to which to take a weak reference
  * @user_data: optional additional data to store alongside the weak ref
  * @destroy: destructor for @user_data, called when the weak ref
@@ -1230,7 +1231,7 @@ struct _TpWeakRef {
  *
  * Return a new weak reference wrapper for @object.
  *
- * Returns: a new weak-reference wrapper
+ * Returns: (transfer full): a new weak-reference wrapper
  *
  * Free-function: tp_weak_ref_destroy()
  *
@@ -1254,7 +1255,7 @@ tp_weak_ref_new (gpointer object,
 }
 
 /**
- * tp_weak_ref_get_user_data:
+ * tp_weak_ref_get_user_data: (skip)
  * @self: a weak reference
  *
  * Return the additional data that was passed to tp_weak_ref_new().
@@ -1271,7 +1272,7 @@ tp_weak_ref_get_user_data (TpWeakRef *self)
 }
 
 /**
- * tp_weak_ref_dup_object:
+ * tp_weak_ref_dup_object: (skip)
  * @self: a weak reference
  *
  * If the weakly referenced object still exists, return a new reference to
@@ -1291,8 +1292,8 @@ tp_weak_ref_dup_object (TpWeakRef *self)
 }
 
 /**
- * tp_weak_ref_destroy:
- * @self: a weak reference
+ * tp_weak_ref_destroy: (skip)
+ * @self: (transfer full): a weak reference
  *
  * Free a weak reference wrapper. This drops the weak reference to the
  * object (if it still exists), and frees the user data with the user-supplied
@@ -1383,9 +1384,9 @@ tp_weak_ref_destroy (TpWeakRef *self)
 
 /**
  * tp_simple_async_report_success_in_idle:
- * @source: the source object
- * @callback: the callback
- * @user_data: user data for @callback
+ * @source: (allow-none): the source object
+ * @callback: (scope async): the callback
+ * @user_data: (closure): user data for @callback
  * @source_tag: the source tag for the #GSimpleAsyncResult
  *
  * Create a new #GSimpleAsyncResult with no operation result, and call
@@ -1632,7 +1633,7 @@ _tp_create_channel_request_list (TpSimpleClientFactory *factory,
  * _g_utf8_make_valid<!-- -->() function, and will be deprecated as
  * soon as the glib one becomes public.
  *
- * Returns: a new valid UTF8 string
+ * Returns: (transfer full): a new valid UTF8 string
  *
  * Since: 0.13.15
  */
diff --git a/telepathy-glib/util.h b/telepathy-glib/util.h
index cad2507ce..3dcf35c7f 100644
--- a/telepathy-glib/util.h
+++ b/telepathy-glib/util.h
@@ -38,6 +38,10 @@ G_BEGIN_DECLS
 gboolean tp_g_ptr_array_contains (GPtrArray *haystack, gpointer needle);
 void tp_g_ptr_array_extend (GPtrArray *target, GPtrArray *source);
 
+#ifndef __GI_SCANNER__
+/* Functions with _new in their names confuse the g-i scanner, but these
+ * are all (skip)'d anyway. */
+
 GValue *tp_g_value_slice_new (GType type) G_GNUC_WARN_UNUSED_RESULT;
 
 GValue *tp_g_value_slice_new_boolean (gboolean b) G_GNUC_WARN_UNUSED_RESULT;
@@ -62,6 +66,8 @@ GValue *tp_g_value_slice_new_static_boxed (GType type, gconstpointer p)
 GValue *tp_g_value_slice_new_take_boxed (GType type, gpointer p)
   G_GNUC_WARN_UNUSED_RESULT;
 
+#endif
+
 void tp_g_value_slice_free (GValue *value);
 
 GValue *tp_g_value_slice_dup (const GValue *value) G_GNUC_WARN_UNUSED_RESULT;