Bug 624483: GDBusSubtreeEnumerateFunc clarification

Clarify a couple of things in the docs:

  1) you must return flat names (no slashes)

  2) g_strfreev() will be called on the result

  3) a benefit of using the DISPATCH_TO_UNENUMERATED flag

diff --git a/gio/gdbusconnection.h b/gio/gdbusconnection.h
index b94e1ab..7d9642e 100644 (file)
--- a/gio/gdbusconnection.h
+++ b/gio/gdbusconnection.h
@@ -306,6 +306,16 @@ gboolean         g_dbus_connection_unregister_object          (GDBusConnection
  *
  * The type of the @enumerate function in #GDBusSubtreeVTable.
  *
+ * This function is called when generating introspection data and also
+ * when preparing to dispatch incoming messages in the event that the
+ * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
+ * specified (ie: to verify that the object path is valid).
+ *
+ * Hierarchies are not supported; the items that you return should not
+ * contain the '/' character.
+ *
+ * The return value will be freed with g_strfreev().
+ *
  * Returns: A newly allocated array of strings for node names that are children of @object_path.
  *
  * Since: 2.26