[Telepathy-commits] [telepathy-glib/master] Document tp_dbus_properties_mixin_make_properties_hash

[Will Thompson]

---
 docs/reference/telepathy-glib-sections.txt |    1 +
 telepathy-glib/dbus-properties-mixin.c     |   18 ++++++++++++++++++
 2 files changed, 19 insertions(+), 0 deletions(-)

diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index 9ab5b4b..89e5ddc 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -1458,6 +1458,7 @@ tp_dbus_properties_mixin_class_init
 tp_dbus_properties_mixin_implement_interface
 tp_dbus_properties_mixin_iface_init
 tp_dbus_properties_mixin_get
+tp_dbus_properties_mixin_make_properties_hash
 </SECTION>
 
 <SECTION>
diff --git a/telepathy-glib/dbus-properties-mixin.c b/telepathy-glib/dbus-properties-mixin.c
index 1731260..07c6e79 100644
--- a/telepathy-glib/dbus-properties-mixin.c
+++ b/telepathy-glib/dbus-properties-mixin.c
@@ -753,6 +753,24 @@ tp_dbus_properties_mixin_get (GObject *self,
 }
 
 
+/**
+ * tp_dbus_properties_mixin_make_properties_hash:
+ * @object: an object which uses the D-Bus properties mixin
+ * @first_interface: the interface of the first property to be retrieved
+ * @first_property: the name of the first property to be retrieved
+ * @...: more (interface name, property name) pairs, terminated by %NULL.
+ *
+ * Retrieves the values of several D-Bus properties from an object, and builds
+ * a hash mapping the fully-qualified name of the property to its value.  This
+ * is equivalent to calling tp_dbus_properties_mixin_get() for each property
+ * and building the table yourself, with the proviso that this function will
+ * g_assert() if retrieving a property fails (for instance, because it does not
+ * exist).
+ *
+ * Returns: a hash table mapping (gchar *) fully-qualified property names to
+ *          GValues, which must be freed by the caller (at which point its
+ *          contents will also be freed).
+ */
 GHashTable *
 tp_dbus_properties_mixin_make_properties_hash (
     GObject *object,
-- 
1.5.6.5