From 2b3754fadcdd3a6a0b23cc9d65ab2723e3a4ea70 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Tue, 31 May 2011 16:18:24 +0100 Subject: [PATCH 10/14] specialized types: improve documentation and document more things --- dbus/dbus-gtype-specialized.c | 100 +++++++++++++++++++++++++++++++--- dbus/dbus-gtype-specialized.h | 5 +- doc/reference/dbus-glib-sections.txt | 1 + 3 files changed, 95 insertions(+), 11 deletions(-) diff --git a/dbus/dbus-gtype-specialized.c b/dbus/dbus-gtype-specialized.c index 4964c4b..702e8e9 100644 --- a/dbus/dbus-gtype-specialized.c +++ b/dbus/dbus-gtype-specialized.c @@ -61,6 +61,71 @@ * the latter. I also need to add some examples. */ +/** + * DBUS_TYPE_G_BOOLEAN_ARRAY: + * + * Expands to a function call returning the #GType of a #GArray of #gboolean + * (corresponding to the D-Bus signature "ab"). + */ + +/** + * DBUS_TYPE_G_INT_ARRAY: + * + * Expands to a function call returning the #GType of a #GArray of #gint + * (corresponding to the D-Bus signature "ai"). + */ + +/** + * DBUS_TYPE_G_UINT_ARRAY: + * + * Expands to a function call returning the #GType of a #GArray of #guint + * (corresponding to the D-Bus signature "au"). + */ + +/** + * DBUS_TYPE_G_INT64_ARRAY: + * + * Expands to a function call returning the #GType of a #GArray of #gint64 + * (corresponding to the D-Bus signature "ax"). + */ + +/** + * DBUS_TYPE_G_UINT64_ARRAY: + * + * Expands to a function call returning the #GType of a #GArray of #guint64 + * (corresponding to the D-Bus signature "at"). + */ + +/** + * DBUS_TYPE_G_UCHAR_ARRAY: + * + * Expands to a function call returning the #GType of a #GArray of #guchar + * (corresponding to the D-Bus signature "ay"). + * + * Note that this is not the same thing as a #GByteArray! dbus-glib does not + * know about the #GByteArray type. + */ + +/** + * DBUS_TYPE_G_OBJECT_ARRAY: + * + * Expands to a function call returning the #GType of a #GPtrArray of #GObject. + * + * Use this type with caution: it can sometimes be used as a representation + * of arrays whose D-Bus signature is "ao" (transferred as an array of object + * paths), but the conventional type for such arrays is + * (dbus_g_type_get_collection ("GPtrArray", + * DBUS_TYPE_G_OBJECT_PATH)). + */ + +/** + * DBUS_TYPE_G_STRING_STRNG_HASHTABLE: + * + * Expands to a function call returning the #GType of a #GHashTable where the + * keys are strings and the values are also strings (corresponding to the + * D-Bus signature "a{ss}"). + */ + typedef enum { DBUS_G_SPECTYPE_COLLECTION, DBUS_G_SPECTYPE_MAP, @@ -351,6 +416,8 @@ _dbus_g_type_register_struct (const char *name, * @map_type: a gtype of a map specialization * * Peek the vtable for a given map specialization + * + * Returns: the vtable */ const DBusGTypeSpecializedMapVtable* dbus_g_type_map_peek_vtable (GType map_type) { @@ -368,6 +435,8 @@ const DBusGTypeSpecializedMapVtable* dbus_g_type_map_peek_vtable (GType map_type * @collection_type: a gtype of a collection specialization * * Peek the vtable for a given collection specialization + * + * Returns: the vtable */ const DBusGTypeSpecializedCollectionVtable* dbus_g_type_collection_peek_vtable (GType collection_type) { @@ -382,9 +451,11 @@ const DBusGTypeSpecializedCollectionVtable* dbus_g_type_collection_peek_vtable ( /** * dbus_g_type_struct_peek_vtable: - * @collection_type: a gtype of a struct specialization + * @struct_type: a gtype of a struct specialization * * Peek the vtable for a given struct specialization + * + * Returns: the vtable */ const DBusGTypeSpecializedStructVtable* dbus_g_type_struct_peek_vtable (GType struct_type) { @@ -740,11 +811,18 @@ dbus_g_type_specialized_construct (GType gtype) /** * dbus_g_type_collection_get_fixed: - * @deprecated: maybe? + * @value: a GValue containing a boxed specialized collection + * @data_ret: used to return a pointer to the fixed data, which must not be + * modified + * @len_ret: used to return the length + * + * If the collection has elements of fixed size (i.e. a fundamental type), + * return the contents of the array. Otherwise, it is an error to call this + * function. * - * if the collection has elements of fixed size (i.e. a fundamental type), - * return the contents of the array. - * Its pretty obscure and I don't think anyone uses it. + * It's probably a bad idea to call this. + * + * Returns: %TRUE on success */ gboolean dbus_g_type_collection_get_fixed (GValue *value, @@ -799,6 +877,14 @@ dbus_g_type_collection_value_iterate (const GValue *va iterator, user_data); } +/** + * DBusGTypeSpecializedAppendContext: + * @val: the #GValue containing the array to which you're appending + * @specialization_type: the #GType of the array's elements + * + * A context for appending. There are more fields, which are private. + */ + typedef struct { GValue *val; GType specialization_type; @@ -809,7 +895,6 @@ typedef struct { * dbus_g_type_specialized_init_append: * @value: a #GValue containing an instance of specialized type * @ctx: a #DBusGTypeSpecializedAppendContext in which to return a new appending context. - * @deprecated: maybe i'll deprecate this as its a bit wank. * * Create a new context for adding elements to a collection or key/value pairs * to a map. You generally don't need or want to use this.. @@ -838,7 +923,6 @@ dbus_g_type_specialized_init_append (GValue *value, DBusGTypeSpecializedAppendCo * dbus_g_type_specialized_collection_append: * @ctx: a context created by #dbus_g_type_specialized_init_append * @elt: a GValue containing an element to append to the collection. - * @deprecated: maybe i'll deprecate this as its a bit wank. * * Appends a given element to the end of a collection. */ @@ -853,7 +937,6 @@ dbus_g_type_specialized_collection_append (DBusGTypeSpecializedAppendContext *ct /** * dbus_g_type_specialized_collection_end_append: * @ctx: a context created by #dbus_g_type_specialized_init_append - * @deprecated: maybe i'll deprecate this as its a bit wank. * * Finish appending elements to a given collection */ @@ -870,7 +953,6 @@ dbus_g_type_specialized_collection_end_append (DBusGTypeSpecializedAppendContext * @ctx: a context created by #dbus_g_type_specialized_init_append * @key: a GValue containing a key, whose contents will be stolen by @ctx * @val: a GValue containing a value, whose contents will be stolen by @ctx - * @deprecated: maybe i'll deprecate this as its a bit wank. * * Inserts the given key/value pair into the map instance. */ diff --git a/dbus/dbus-gtype-specialized.h b/dbus/dbus-gtype-specialized.h index 8c60182..8281ae1 100644 --- a/dbus/dbus-gtype-specialized.h +++ b/dbus/dbus-gtype-specialized.h @@ -62,6 +62,7 @@ typedef struct { /* public */ GValue *val; GType specialization_type; + /*< private >*/ /* padding */ gpointer b; guint c; @@ -80,8 +81,8 @@ void dbus_g_type_specialized_map_append (DBusGTypeSpecial gboolean dbus_g_type_collection_get_fixed (GValue *value, - gpointer *data, - guint *len); + gpointer *data_ret, + guint *len_ret); void dbus_g_type_collection_value_iterate (const GValue *value, DBusGTypeSpecializedCollectionIterator iterator, diff --git a/doc/reference/dbus-glib-sections.txt b/doc/reference/dbus-glib-sections.txt index a1b27a1..fce4c7a 100644 --- a/doc/reference/dbus-glib-sections.txt +++ b/doc/reference/dbus-glib-sections.txt @@ -171,6 +171,7 @@ dbus_g_type_register_collection dbus_g_type_register_map dbus_g_type_map_peek_vtable dbus_g_type_collection_peek_vtable +dbus_g_type_struct_peek_vtable dbus_g_type_register_struct dbus_g_value_build_g_variant dbus_g_value_parse_g_variant -- 1.7.5.3