big docs cleanup

We're now back at 100% docs coverage with no warnings.

10 files changed, 520 insertions, 219 deletions

diff --git a/client/dconf-client.c b/client/dconf-client.c
index eced4f1..fad445c 100644
--- a/client/dconf-client.c
+++ b/client/dconf-client.c
@@ -25,6 +25,30 @@
 #include "../engine/dconf-engine.h"
 #include <glib-object.h>
 
+/**
+ * SECTION:client
+ * @title: DConfClient
+ * @short_description: Direct read and write access to DConf, based on GDBus
+ *
+ * This is the primary client interface to dconf.
+ *
+ * It allows applications to directly read from and write to the dconf
+ * database.  Applications can subscribe to change notifications.
+ *
+ * Most applications probably don't want to access dconf directly and
+ * would be better off using something like #GSettings.
+ *
+ * Please note that the API of libdconf is not stable in any way.  It
+ * has changed in incompatible ways in the past and there will be
+ * further changes in the future.
+ **/
+
+/**
+ * DConfClient:
+ *
+ * The main object for interacting with dconf.  This is a #GObject, so
+ * you should manage it with g_object_ref() and g_object_unref().
+ **/
 struct _DConfClient
 {
   GObject parent_instance;
@@ -64,6 +88,45 @@ dconf_client_class_init (DConfClientClass *class)
 {
   class->finalize = dconf_client_finalize;
 
+  /**
+   * DConfClient::changed:
+   * @client: the #DConfClient reporting the change
+   * @prefix: the prefix under which the changes happened
+   * @changes: the list of paths that were changed, relative to @prefix
+   * @tag: the tag for the change, if it originated from the service
+   *
+   * This signal is emitted when the #DConfClient has a possible change
+   * to report.  The signal is an indication that a change may have
+   * occured; it's possible that the keys will still have the same value
+   * as before.
+   *
+   * To ensure that you receive notification about changes to paths that
+   * you are interested in you must call dconf_client_watch_fast() or
+   * dconf_client_watch_sync().  You may still receive notifications for
+   * paths that you did not explicitly watch.
+   *
+   * @prefix will be an absolute dconf path; see dconf_is_path().
+   * @changes is a %NULL-terminated array of dconf rel paths; see
+   * dconf_is_rel_path().
+   *
+   * @tag is an opaque tag string, or %NULL.  The only thing you should
+   * do with @tag is to compare it to tag values returned by
+   * dconf_client_write_sync() or dconf_client_change_sync().
+   *
+   * The number of changes being reported is equal to the length of
+   * @changes.  Appending each item in @changes to @prefix will give the
+   * absolute path of each changed item.
+   *
+   * If a single key has changed then @prefix will be equal to the key
+   * and @changes will contain a single item: the empty string.
+   *
+   * If a single dir has changed (indicating that any key under the dir
+   * may have changed) then @prefix will be equal to the dir and
+   * @changes will contain a single empty string.
+   *
+   * If more than one change is being reported then @changes will have
+   * more than one item.
+   **/
   dconf_client_signals[SIGNAL_CHANGED] = g_signal_new ("changed", DCONF_TYPE_CLIENT, G_SIGNAL_RUN_LAST,
                                                        0, NULL, NULL, NULL, G_TYPE_NONE, 3,
                                                        G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE,
@@ -132,6 +195,13 @@ dconf_client_free_weak_ref (gpointer data)
   g_slice_free (GWeakRef, weak_ref);
 }
 
+/**
+ * dconf_client_new:
+ *
+ * Creates a new #DConfClient.
+ *
+ * Returns: a new #DConfClient
+ **/
 DConfClient *
 dconf_client_new (void)
 {
@@ -147,6 +217,20 @@ dconf_client_new (void)
   return client;
 }
 
+/**
+ * dconf_client_read:
+ * @client: a #DConfClient
+ * @key: the key to read the value of
+ *
+ * Reads the current value of @key.
+ *
+ * If @key exists, its value is returned.  Otherwise, %NULL is returned.
+ *
+ * If there are outstanding "fast" changes in progress they may affect
+ * the result of this call.
+ *
+ * Returns: a #GVariant, or %NULL
+ **/
 GVariant *
 dconf_client_read (DConfClient *client,
                    const gchar *key)
@@ -156,6 +240,23 @@ dconf_client_read (DConfClient *client,
   return dconf_engine_read (client->engine, NULL, key);
 }
 
+/**
+ * dconf_client_list:
+ * @client: a #DConfClient
+ * @dir: the dir to list the contents of
+ * @length: the length of the returned list
+ *
+ * Gets the list of all dirs and keys immediately under @dir.
+ *
+ * If @length is non-%NULL then it will be set to the length of the
+ * returned array.  In any case, the array is %NULL-terminated.
+ *
+ * IF there are outstanding "fast" changes in progress then this call
+ * may return inaccurate results with respect to those outstanding
+ * changes.
+ *
+ * Returns: an array of strings, never %NULL.
+ **/
 gchar **
 dconf_client_list (DConfClient *client,
                    const gchar *dir,
@@ -166,6 +267,21 @@ dconf_client_list (DConfClient *client,
   return dconf_engine_list (client->engine, dir, length);
 }
 
+/**
+ * dconf_client_is_writable:
+ * @client: a #DConfClient
+ * @key: the key to check for writability
+ *
+ * Checks if @key is writable (ie: the key has no locks).
+ *
+ * This call does not verify that writing to the key will actually be
+ * successful.  It only checks that the database is writable and that
+ * there are no locks affecting @key.  Other issues (such as a full disk
+ * or an inability to connect to the bus and start the service) may
+ * cause the write to fail.
+ *
+ * Returns: %TRUE is @key is writable
+ **/
 gboolean
 dconf_client_is_writable (DConfClient *client,
                           const gchar *key)
@@ -175,6 +291,33 @@ dconf_client_is_writable (DConfClient *client,
   return dconf_engine_is_writable (client->engine, key);
 }
 
+/**
+ * dconf_client_write_fast:
+ * @client: a #DConfClient
+ * @key: the key to write to
+ * @value: a #GVariant, the value to write
+ * @error: a pointer to a %NULL #GError, or %NULL
+ *
+ * Writes @value to the given @key, or reset @key to its default value.
+ *
+ * If @value is %NULL then @key is reset to its default value (which may
+ * be completely unset), otherwise @value becomes the new value.
+ *
+ * This call merely queues up the write and returns immediately, without
+ * blocking.  The only errors that can be detected or reported at this
+ * point are attempts to write to read-only keys.
+ *
+ * A local copy of the written value is kept so that calls to
+ * dconf_client_read() that occur before the service actually makes the
+ * change will return the new value.
+ *
+ * If the write is queued then a change signal will be directly emitted.
+ * If this function is being called from the main context of @client
+ * then the signal is emitted before this function returns; otherwise it
+ * is scheduled on the main context.
+ *
+ * Returns: %TRUE if the write was queued
+ **/
 gboolean
 dconf_client_write_fast (DConfClient  *client,
                          const gchar  *key,
@@ -193,6 +336,31 @@ dconf_client_write_fast (DConfClient  *client,
   return success;
 }
 
+/**
+ * dconf_client_write_sync:
+ * @client: a #DConfClient
+ * @key: the key to write to
+ * @value: a #GVariant, the value to write
+ * @tag: (out) (allow-none): the tag from this write
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a pointer to a %NULL #GError, or %NULL
+ *
+ * Write @value to the given @key, or reset @key to its default value.
+ *
+ * If @value is %NULL then @key is reset to its default value (which may
+ * be completely unset), otherwise @value becomes the new value.
+ *
+ * This call blocks until the write is complete.  This call will
+ * therefore detect and report all cases of failure.  If the modified
+ * key is currently being watched then a signal will be emitted from the
+ * main context of @client (once the signal arrives from the service).
+ *
+ * If @tag is non-%NULL then it is set to the unique tag associated with
+ * this write.  This is the same tag that will appear in the following
+ * change signal.
+ *
+ * Returns: %TRUE on success, else %FALSE with @error set
+ **/
 gboolean
 dconf_client_write_sync (DConfClient   *client,
                          const gchar   *key,
@@ -213,6 +381,31 @@ dconf_client_write_sync (DConfClient   *client,
   return success;
 }
 
+/**
+ * dconf_client_change_fast:
+ * @client: a #DConfClient
+ * @changeset: the changeset describing the requested change
+ * @error: a pointer to a %NULL #GError, or %NULL
+ *
+ * Performs the change operation described by @changeset.
+ *
+ * Once @changeset is passed to this call it can no longer be modified.
+ *
+ * This call merely queues up the write and returns immediately, without
+ * blocking.  The only errors that can be detected or reported at this
+ * point are attempts to write to read-only keys.
+ *
+ * A local copy of the written value is kept so that calls to
+ * dconf_client_read() that occur before the service actually makes the
+ * change will return the new value.
+ *
+ * If the write is queued then a change signal will be directly emitted.
+ * If this function is being called from the main context of @client
+ * then the signal is emitted before this function returns; otherwise it
+ * is scheduled on the main context.
+ *
+ * Returns: %TRUE if the requested changed was queued
+ **/
 gboolean
 dconf_client_change_fast (DConfClient     *client,
                           DConfChangeset  *changeset,
@@ -223,6 +416,30 @@ dconf_client_change_fast (DConfClient     *client,
   return dconf_engine_change_fast (client->engine, changeset, error);
 }
 
+/**
+ * dconf_client_change_sync:
+ * @client: a #DConfClient
+ * @changeset: the changeset describing the requested change
+ * @tag: (out) (allow-none): the tag from this write
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a pointer to a %NULL #GError, or %NULL
+ *
+ * Performs the change operation described by @changeset.
+ *
+ * Once @changeset is passed to this call it can no longer be modified.
+ *
+ * This call blocks until the change is complete.  This call will
+ * therefore detect and report all cases of failure.  If any of the
+ * modified keys are currently being watched then a signal will be
+ * emitted from the main context of @client (once the signal arrives
+ * from the service).
+ *
+ * If @tag is non-%NULL then it is set to the unique tag associated with
+ * this change.  This is the same tag that will appear in the following
+ * change signal.
+ *
+ * Returns: %TRUE on success, else %FALSE with @error set
+ **/
 gboolean
 dconf_client_change_sync (DConfClient     *client,
                           DConfChangeset  *changeset,
@@ -235,6 +452,23 @@ dconf_client_change_sync (DConfClient     *client,
   return dconf_engine_change_sync (client->engine, changeset, tag, error);
 }
 
+/**
+ * dconf_client_watch_fast:
+ * @client: a #DConfClient
+ * @path: a path to watch
+ *
+ * Requests change notifications for @path.
+ *
+ * If @path is a key then the single key is monitored.  If @path is a
+ * dir then all keys under the dir are monitored.
+ *
+ * This function queues the watch request with D-Bus and returns
+ * immediately.  There is a very slim chance that the dconf database
+ * could change before the watch is actually established.  If that is
+ * the case then a synthetic change signal will be emitted.
+ *
+ * Errors are silently ignored.
+ **/
 void
 dconf_client_watch_fast (DConfClient *client,
                          const gchar *path)
@@ -244,6 +478,22 @@ dconf_client_watch_fast (DConfClient *client,
   dconf_engine_watch_fast (client->engine, path);
 }
 
+/**
+ * dconf_client_watch_sync:
+ * @client: a #DConfClient
+ * @path: a path to watch
+ *
+ * Requests change notifications for @path.
+ *
+ * If @path is a key then the single key is monitored.  If @path is a
+ * dir then all keys under the dir are monitored.
+ *
+ * This function submits each of the the various watch requests that are
+ * required to monitor a key and waits until each of them returns.  By
+ * the time this function returns, the watch has been established.
+ *
+ * Errors are silently ignored.
+ **/
 void
 dconf_client_watch_sync (DConfClient *client,
                          const gchar *path)
@@ -253,6 +503,19 @@ dconf_client_watch_sync (DConfClient *client,
   dconf_engine_watch_sync (client->engine, path);
 }
 
+/**
+ * dconf_client_unwatch_fast:
+ * @client: a #DConfClient
+ * @path: a path previously watched
+ *
+ * Cancels the effect of a previous call to dconf_client_watch_fast().
+ *
+ * This call returns immediately.
+ *
+ * It is still possible that change signals are received after this call
+ * had returned (watching guarantees notification of changes, but
+ * unwatching does not guarantee no notifications).
+ **/
 void
 dconf_client_unwatch_fast (DConfClient *client,
                            const gchar *path)
@@ -262,6 +525,19 @@ dconf_client_unwatch_fast (DConfClient *client,
   dconf_engine_unwatch_fast (client->engine, path);
 }
 
+/**
+ * dconf_client_unwatch_sync:
+ * @client: a #DConfClient
+ * @path: a path previously watched
+ *
+ * Cancels the effect of a previous call to dconf_client_watch_sync().
+ *
+ * This function submits each of the various unwatch requests and waits
+ * until each of them returns.  It is still possible that change signals
+ * are received after this call has returned (watching guarantees
+ * notification of changes, but unwatching does not guarantee no
+ * notifications).
+ **/
 void
 dconf_client_unwatch_sync (DConfClient *client,
                            const gchar *path)
diff --git a/client/extra-docs.c b/client/extra-docs.c
deleted file mode 100644
index 2f12951..0000000
--- a/client/extra-docs.c
+++ /dev/null
@@ -1,89 +0,0 @@
-/* extra docs here until we can emit them with Vala */
-
-/**
- * SECTION:client
- * @title: DConfClient
- * @short_description: Direct read and write access to DConf, based on GDBus
- *
- * This is a simple class that allows an application to directly read
- * from and write to the dconf database.  There is also a very simple
- * mechanism for requesting and receiving notification of changes but
- * not robust mechanism for dispatching change notifications to multiple
- * listeners.
- *
- * Most applications probably don't want to access dconf directly and
- * would be better off using something like #GSettings.
- **/
-
-/**
- * DConfWatchFunc:
- * @client: the #DConfClient emitting the notification
- * @path: the path at which the change occured
- * @items: the items that were changed, given as relative paths
- * @n_items: the length of @items
- * @tag: the tag associated with the change
- * @user_data: the user data given to dconf_client_new()
- *
- * This is the type of the callback given to dconf_client_new().
- *
- * This function is called in response to changes occuring to the dconf
- * database that @client is associated with.
- *
- * @path can either be a key or a dir.  If @path is a key then @items
- * will be empty and the notification should be taken to mean that one
- * key -- the key named by @path -- may have changed.
- *
- * If @path is a dir and @items is empty then it is an indication that
- * any key under @path may have changed.
- *
- * Otherwise (if @items is non-empty) then the set of affected keys is
- * the same as if the watch function had been called multiple times for
- * each item in the array appended to @path.  This includes the
- * possibility of the resulting path being a dir.
- **/
-
-/**
- * DConfClient:
- *
- * An opaque structure type.  May only be used with the following
- * functions.
- **/
-
-/**
- * dconf_client_write_finish:
- * @client: a #DConfClient
- * @result: the #GAsyncResult passed to the #GAsyncReadyCallback
- * @tag: (out) (allow-none): the tag from this write
- * @error: a pointer to a #GError, or %NULL
- *
- * Collects the result from a prior call to dconf_client_write_async().
- **/
-
-/**
- * dconf_client_set_locked_finish:
- * @client: a #DConfClient
- * @result: the #GAsyncResult passed to the #GAsyncReadyCallback
- * @error: a pointer to a #GError, or %NULL
- *
- * Collects the result from a prior call to
- * dconf_client_set_locked_async().
- **/
-
-/**
- * dconf_client_watch_finish:
- * @client: a #DConfClient
- * @result: the #GAsyncResult passed to the #GAsyncReadyCallback
- * @error: a pointer to a #GError, or %NULL
- *
- * Collects the result from a prior call to dconf_client_watch_async().
- **/
-
-/**
- * dconf_client_unwatch_finish:
- * @client: a #DConfClient
- * @result: the #GAsyncResult passed to the #GAsyncReadyCallback
- * @error: a pointer to a #GError, or %NULL
- *
- * Collects the result from a prior call to
- * dconf_client_unwatch_async().
- **/
diff --git a/common/dconf-changeset.c b/common/dconf-changeset.c
index 1dcee39..195841a 100644
--- a/common/dconf-changeset.c
+++ b/common/dconf-changeset.c
@@ -25,12 +25,38 @@
 #include <string.h>
 #include <stdlib.h>
 
+/**
+ * SECTION:changeset
+ * @title: DConfChangeset
+ * @Short_description: A set of changes to a dconf database
+ *
+ * #DConfChangeset represents a set of changes that can be made to a
+ * dconf database.  Currently supported operations are writing new
+ * values to keys and resetting keys and dirs.
+ *
+ * Create the changeset with dconf_changeset_new() and populate it with
+ * dconf_changeset_set().  Submit it to dconf with
+ * dconf_client_change_fast() or dconf_client_change_sync().
+ * dconf_changeset_new_write() is a convenience constructor for the
+ * common case of writing or resetting a single value.
+ **/
+
+/**
+ * DConfChangeset:
+ *
+ * This is a reference counted opaque structure type.  It is not a
+ * #GObject.
+ *
+ * Use dconf_changeset_ref() and dconf_changeset_unref() to manipuate
+ * references.
+ **/
+
 struct _DConfChangeset
 {
   GHashTable *table;
   gint ref_count;
 
-  gchar *root;
+  gchar *prefix;
   const gchar **paths;
   GVariant **values;
 };
@@ -52,47 +78,55 @@ unref_gvariant0 (gpointer data)
 DConfChangeset *
 dconf_changeset_new (void)
 {
-  DConfChangeset *change;
+  DConfChangeset *changeset;
 
-  change = g_slice_new0 (DConfChangeset);
-  change->table = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, unref_gvariant0);
-  change->ref_count = 1;
+  changeset = g_slice_new0 (DConfChangeset);
+  changeset->table = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, unref_gvariant0);
+  changeset->ref_count = 1;
 
-  return change;
+  return changeset;
 }
 
 /**
  * dconf_changeset_unref:
- * @change: a #DConfChangeset
+ * @changeset: a #DConfChangeset
  *
  * Releases a #DConfChangeset reference.
  **/
 void
-dconf_changeset_unref (DConfChangeset *change)
+dconf_changeset_unref (DConfChangeset *changeset)
 {
-  if (g_atomic_int_dec_and_test (&change->ref_count))
+  if (g_atomic_int_dec_and_test (&changeset->ref_count))
     {
-      g_free (change->root);
-      g_free (change->paths);
-      g_free (change->values);
+      g_free (changeset->prefix);
+      g_free (changeset->paths);
+      g_free (changeset->values);
 
-      g_hash_table_unref (change->table);
+      g_hash_table_unref (changeset->table);
 
-      g_slice_free (DConfChangeset, change);
+      g_slice_free (DConfChangeset, changeset);
     }
 }
 
+/**
+ * dconf_changeset_ref:
+ * @changeset: a #DConfChangeset
+ *
+ * Increases the reference count on @changeset
+ *
+ * Returns: @changeset
+ **/
 DConfChangeset *
-dconf_changeset_ref (DConfChangeset *change)
+dconf_changeset_ref (DConfChangeset *changeset)
 {
-  g_atomic_int_inc (&change->ref_count);
+  g_atomic_int_inc (&changeset->ref_count);
 
-  return change;
+  return changeset;
 }
 
 /**
  * dconf_changeset_set:
- * @change: a #DConfChangeset
+ * @changeset: a #DConfChangeset
  * @path: a path to modify
  * @value: the value for the key, or %NULL to reset
  *
@@ -105,11 +139,11 @@ dconf_changeset_ref (DConfChangeset *change)
  * %NULL.  It is not permitted to assign a #GVariant value to a dir.
  **/
 void
-dconf_changeset_set (DConfChangeset *change,
+dconf_changeset_set (DConfChangeset *changeset,
                      const gchar    *path,
                      GVariant       *value)
 {
-  g_return_if_fail (change->root == NULL);
+  g_return_if_fail (changeset->prefix == NULL);
   g_return_if_fail (dconf_is_path (path, NULL));
 
   /* Check if we are performing a path reset */
@@ -123,23 +157,23 @@ dconf_changeset_set (DConfChangeset *change,
       /* When we reset a path we must also reset all keys within that
        * path.
        */
-      g_hash_table_iter_init (&iter, change->table);
+      g_hash_table_iter_init (&iter, changeset->table);
       while (g_hash_table_iter_next (&iter, &key, NULL))
         if (g_str_has_prefix (key, path))
           g_hash_table_iter_remove (&iter);
 
       /* Record the reset itself. */
-      g_hash_table_insert (change->table, g_strdup (path), NULL);
+      g_hash_table_insert (changeset->table, g_strdup (path), NULL);
     }
 
   /* else, just a normal value write or reset */
   else
-    g_hash_table_insert (change->table, g_strdup (path), value ? g_variant_ref_sink (value) : NULL);
+    g_hash_table_insert (changeset->table, g_strdup (path), value ? g_variant_ref_sink (value) : NULL);
 }
 
 /**
  * dconf_changeset_get:
- * @change: a #DConfChangeset
+ * @changeset: a #DConfChangeset
  * @key: the key to check
  * @value: a return location for the value, or %NULL
  *
@@ -156,13 +190,13 @@ dconf_changeset_set (DConfChangeset *change,
  * Returns: %TRUE if the key is being modified by the change
  */
 gboolean
-dconf_changeset_get (DConfChangeset  *change,
+dconf_changeset_get (DConfChangeset  *changeset,
                      const gchar     *key,
                      GVariant       **value)
 {
   gpointer tmp;
 
-  if (!g_hash_table_lookup_extended (change->table, key, NULL, &tmp))
+  if (!g_hash_table_lookup_extended (changeset->table, key, NULL, &tmp))
     return FALSE;
 
   if (value)
@@ -173,10 +207,10 @@ dconf_changeset_get (DConfChangeset  *change,
 
 /**
  * dconf_changeset_is_similar_to:
- * @change: a #DConfChangeset
+ * @changeset: a #DConfChangeset
  * @other: another #DConfChangeset
  *
- * Checks if @change is similar to @other.
+ * Checks if @changeset is similar to @other.
  *
  * Two changes are considered similar if they write to the exact same
  * set of keys.  The values written are not considered.
@@ -193,16 +227,16 @@ dconf_changeset_get (DConfChangeset  *change,
  * Returns: %TRUE if the changes are similar
  **/
 gboolean
-dconf_changeset_is_similar_to (DConfChangeset *change,
+dconf_changeset_is_similar_to (DConfChangeset *changeset,
                                DConfChangeset *other)
 {
   GHashTableIter iter;
   gpointer key;
 
-  if (g_hash_table_size (change->table) != g_hash_table_size (other->table))
+  if (g_hash_table_size (changeset->table) != g_hash_table_size (other->table))
     return FALSE;
 
-  g_hash_table_iter_init (&iter, change->table);
+  g_hash_table_iter_init (&iter, changeset->table);
   while (g_hash_table_iter_next (&iter, &key, NULL))
     if (!g_hash_table_contains (other->table, key))
       return FALSE;
@@ -211,9 +245,23 @@ dconf_changeset_is_similar_to (DConfChangeset *change,
 }
 
 /**
+ * DConfChangesetPredicate:
+ * @path: a path, as per dconf_is_path()
+ * @value: a #GVariant, or %NULL
+ * @user_data: user data pointer
+ *
+ * Callback function type for predicates over items in a
+ * #DConfChangeset.
+ *
+ * Use with dconf_changeset_all().
+ *
+ * Returns: %TRUE if the predicate is met for the given @path and @value
+ **/
+
+/**
  * dconf_changeset_all:
- * @change: a #DConfChangeset
- * @predicate: a #DConfChangePredicate
+ * @changeset: a #DConfChangeset
+ * @predicate: a #DConfChangesetPredicate
  * @user_data: user data to pass to @predicate
  *
  * Checks if all changes in the changeset satisfy @predicate.
@@ -225,17 +273,17 @@ dconf_changeset_is_similar_to (DConfChangeset *change,
  * %FALSE.  If not (including the case of no items) then this function
  * returns %TRUE.
  *
- * Returns: %TRUE if all items in @change satisfy @predicate
+ * Returns: %TRUE if all items in @changeset satisfy @predicate
  */
 gboolean
-dconf_changeset_all (DConfChangeset          *change,
+dconf_changeset_all (DConfChangeset          *changeset,
                      DConfChangesetPredicate  predicate,
                      gpointer                 user_data)
 {
   GHashTableIter iter;
   gpointer key, value;
 
-  g_hash_table_iter_init (&iter, change->table);
+  g_hash_table_iter_init (&iter, changeset->table);
   while (g_hash_table_iter_next (&iter, &key, &value))
     if (!(* predicate) (key, value, user_data))
       return FALSE;
@@ -254,12 +302,12 @@ dconf_changeset_string_ptr_compare (gconstpointer a_p,
 }
 
 static void
-dconf_changeset_build_description (DConfChangeset *change)
+dconf_changeset_build_description (DConfChangeset *changeset)
 {
   gsize prefix_length;
   gint n_items;
 
-  n_items = g_hash_table_size (change->table);
+  n_items = g_hash_table_size (changeset->table);
 
   /* If there are no items then what is there to describe? */
   if (n_items == 0)
@@ -291,7 +339,7 @@ dconf_changeset_build_description (DConfChangeset *change)
     const gchar *first;
     gpointer key;
 
-    g_hash_table_iter_init (&iter, change->table);
+    g_hash_table_iter_init (&iter, changeset->table);
 
     /* We checked above that we have at least one item. */
     if (!g_hash_table_iter_next (&iter, &key, NULL))
@@ -329,7 +377,7 @@ dconf_changeset_build_description (DConfChangeset *change)
           prefix_length--;
       }
 
-    change->root = g_strndup (first, prefix_length);
+    changeset->prefix = g_strndup (first, prefix_length);
   }
 
   /* Pass 2: collect the list of keys, dropping the prefix */
@@ -338,63 +386,94 @@ dconf_changeset_build_description (DConfChangeset *change)
     gpointer key;
     gint i = 0;
 
-    change->paths = g_new (const gchar *, n_items + 1);
+    changeset->paths = g_new (const gchar *, n_items + 1);
 
-    g_hash_table_iter_init (&iter, change->table);
+    g_hash_table_iter_init (&iter, changeset->table);
     while (g_hash_table_iter_next (&iter, &key, NULL))
       {
         const gchar *path = key;
 
-        change->paths[i++] = path + prefix_length;
+        changeset->paths[i++] = path + prefix_length;
       }
-    change->paths[i] = NULL;
+    changeset->paths[i] = NULL;
     g_assert (i == n_items);
 
     /* Sort the list of keys */
-    qsort (change->paths, n_items, sizeof (const gchar *), dconf_changeset_string_ptr_compare);
+    qsort (changeset->paths, n_items, sizeof (const gchar *), dconf_changeset_string_ptr_compare);
   }
 
   /* Pass 3: collect the list of values */
   {
     gint i;
 
-    change->values = g_new (GVariant *, n_items);
+    changeset->values = g_new (GVariant *, n_items);
 
     for (i = 0; i < n_items; i++)
       /* We dropped the prefix when collecting the array.
        * Bring it back temporarily, for the lookup.
        */
-      change->values[i] = g_hash_table_lookup (change->table, change->paths[i] - prefix_length);
+      changeset->values[i] = g_hash_table_lookup (changeset->table, changeset->paths[i] - prefix_length);
   }
 }
 
+/**
+ * dconf_changeset_describe:
+ * @changeset: a #DConfChangeset
+ * @prefix: the prefix under which changes have been requested
+ * @paths: the list of paths changed, relative to @prefix
+ * @values: the list of values changed
+ *
+ * Describes @changeset.
+ *
+ * @prefix and @paths are presented in the same way as they are for the
+ * DConfClient::changed signal.  @values is an array of the same length
+ * as @paths.  For each key described by an element in @paths, @values
+ * will contain either a #GVariant (the requested new value of that key)
+ * or %NULL (to reset a reset).
+ *
+ * The @paths array is returned in an order such that dir will always
+ * come before keys contained within those dirs.
+ *
+ * Returns: the number of changes (the length of @changes and @values).
+ **/
 guint
-dconf_changeset_describe (DConfChangeset       *change,
-                          const gchar         **root,
+dconf_changeset_describe (DConfChangeset       *changeset,
+                          const gchar         **prefix,
                           const gchar * const **paths,
                           GVariant * const    **values)
 {
   gint n_items;
 
-  n_items = g_hash_table_size (change->table);
+  n_items = g_hash_table_size (changeset->table);
 
-  if (n_items && !change->root)
-    dconf_changeset_build_description (change);
+  if (n_items && !changeset->prefix)
+    dconf_changeset_build_description (changeset);
 
-  if (root)
-    *root = change->root;
+  if (prefix)
+    *prefix = changeset->prefix;
 
   if (paths)
-    *paths = change->paths;
+    *paths = changeset->paths;
 
   if (values)
-    *values = change->values;
+    *values = changeset->values;
 
   return n_items;
 }
 
+/**
+ * dconf_changeset_serialise:
+ * @changeset: a #DConfChangeset
+ *
+ * Serialises a #DConfChangeset.
+ *
+ * The returned value has no particular format and should only be passed
+ * to dconf_changeset_deserialise().
+ *
+ * Returns: a floating #GVariant
+ **/
 GVariant *
-dconf_changeset_serialise (DConfChangeset *change)
+dconf_changeset_serialise (DConfChangeset *changeset)
 {
   GVariantBuilder builder;
   GHashTableIter iter;
@@ -402,22 +481,37 @@ dconf_changeset_serialise (DConfChangeset *change)
 
   g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{smv}"));
 
-  g_hash_table_iter_init (&iter, change->table);
+  g_hash_table_iter_init (&iter, changeset->table);
   while (g_hash_table_iter_next (&iter, &key, &value))
     g_variant_builder_add (&builder, "{smv}", key, value);
 
   return g_variant_builder_end (&builder);
 }
 
+/**
+ * dconf_changeset_deserialise:
+ * @serialised: a #GVariant from dconf_changeset_serialise()
+ *
+ * Creates a #DConfChangeset according to a serialised description
+ * returned from an earlier call to dconf_changeset_serialise().
+ *
+ * @serialised has no particular format -- you should only pass a value
+ * that reasulted from an earlier serialise operation.
+ *
+ * This call never fails, even if @serialised is not in the correct
+ * format.  Improperly-formatted parts are simply ignored.
+ *
+ * Returns: a new #DConfChangeset
+ **/
 DConfChangeset *
 dconf_changeset_deserialise (GVariant *serialised)
 {
-  DConfChangeset *change;
+  DConfChangeset *changeset;
   GVariantIter iter;
   const gchar *key;
   GVariant *value;
 
-  change = dconf_changeset_new ();
+  changeset = dconf_changeset_new ();
   g_variant_iter_init (&iter, serialised);
   while (g_variant_iter_loop (&iter, "{&smv}", &key, &value))
     {
@@ -431,18 +525,29 @@ dconf_changeset_deserialise (GVariant *serialised)
       if (value == NULL)
         {
           if (dconf_is_path (key, NULL))
-            g_hash_table_insert (change->table, g_strdup (key), NULL);
+            g_hash_table_insert (changeset->table, g_strdup (key), NULL);
         }
       else
         {
           if (dconf_is_key (key, NULL))
-            g_hash_table_insert (change->table, g_strdup (key), g_variant_ref (value));
+            g_hash_table_insert (changeset->table, g_strdup (key), g_variant_ref (value));
         }
     }
 
-  return change;
+  return changeset;
 }
 
+/**
+ * dconf_changeset_new_write:
+ * @path: a dconf path
+ * @value: a #GVariant, or %NULL
+ *
+ * Creates a new #DConfChangeset with one change.  This is equivalent to
+ * calling dconf_changeset_new() and then dconf_changeset_set() with
+ * @path and @value.
+ *
+ * Returns: a new #DConfChangeset
+ **/
 DConfChangeset *
 dconf_changeset_new_write (const gchar *path,
                            GVariant    *value)
diff --git a/common/dconf-changeset.h b/common/dconf-changeset.h
index de062fa..c2a5435 100644
--- a/common/dconf-changeset.h
+++ b/common/dconf-changeset.h
@@ -26,39 +26,39 @@
 
 typedef struct _DConfChangeset                              DConfChangeset;
 
-typedef gboolean     (* DConfChangesetPredicate)                        (const gchar             *key,
-                                                                         GVariant                *value,
-                                                                         gpointer                 user_data);
+typedef gboolean     (* DConfChangesetPredicate)                        (const gchar              *path,
+                                                                         GVariant                 *value,
+                                                                         gpointer                  user_data);
 
 DConfChangeset *        dconf_changeset_new                             (void);
 
-DConfChangeset *        dconf_changeset_new_write                       (const gchar             *key,
-                                                                         GVariant                *value);
+DConfChangeset *        dconf_changeset_new_write                       (const gchar              *path,
+                                                                         GVariant                 *value);
 
-DConfChangeset *        dconf_changeset_ref                             (DConfChangeset          *changeset);
-void                    dconf_changeset_unref                           (DConfChangeset          *changeset);
+DConfChangeset *        dconf_changeset_ref                             (DConfChangeset           *changeset);
+void                    dconf_changeset_unref                           (DConfChangeset           *changeset);
 
-void                    dconf_changeset_set                             (DConfChangeset          *changeset,
-                                                                         const gchar             *key,
-                                                                         GVariant                *value);
+void                    dconf_changeset_set                             (DConfChangeset           *changeset,
+                                                                         const gchar              *path,
+                                                                         GVariant                 *value);
 
-gboolean                dconf_changeset_get                             (DConfChangeset          *changeset,
-                                                                         const gchar             *key,
-                                                                         GVariant               **value);
+gboolean                dconf_changeset_get                             (DConfChangeset           *changeset,
+                                                                         const gchar              *key,
+                                                                         GVariant                **value);
 
-gboolean                dconf_changeset_is_similar_to                   (DConfChangeset          *changeset,
-                                                                         DConfChangeset          *other);
+gboolean                dconf_changeset_is_similar_to                   (DConfChangeset           *changeset,
+                                                                         DConfChangeset           *other);
 
-gboolean                dconf_changeset_all                             (DConfChangeset          *changeset,
-                                                                         DConfChangesetPredicate  predicate,
-                                                                         gpointer                 user_data);
+gboolean                dconf_changeset_all                             (DConfChangeset           *changeset,
+                                                                         DConfChangesetPredicate   predicate,
+                                                                         gpointer                  user_data);
 
-guint                   dconf_changeset_describe                        (DConfChangeset       *changeset,
-                                                                         const gchar         **change_root,
-                                                                         const gchar * const **changes,
-                                                                         GVariant * const    **values);
+guint                   dconf_changeset_describe                        (DConfChangeset           *changeset,
+                                                                         const gchar             **prefix,
+                                                                         const gchar * const     **paths,
+                                                                         GVariant * const        **values);
 
-GVariant *              dconf_changeset_serialise                       (DConfChangeset          *changeset);
-DConfChangeset *        dconf_changeset_deserialise                     (GVariant                *serialised);
+GVariant *              dconf_changeset_serialise                       (DConfChangeset           *changeset);
+DConfChangeset *        dconf_changeset_deserialise                     (GVariant                 *serialised);
 
 #endif /* __dconf_changeset_h__ */
diff --git a/common/dconf-paths.c b/common/dconf-paths.c
index 6f82ee9..33a6f74 100644
--- a/common/dconf-paths.c
+++ b/common/dconf-paths.c
@@ -106,13 +106,14 @@
  * dconf_is_path:
  * @string: a string
  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
- * Returns: %TRUE if @string is a path
  *
  * Checks if @string is a valid dconf path.  dconf keys must start with
  * '/' and not contain '//'.
  *
  * A dconf path may be either a key or a dir.  See dconf_is_key() and
  * dconf_is_dir() for examples of each.
+ *
+ * Returns: %TRUE if @string is a path
  **/
 gboolean
 dconf_is_path (const gchar  *string,
@@ -127,7 +128,6 @@ dconf_is_path (const gchar  *string,
  * dconf_is_key:
  * @string: a string
  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
- * Returns: %TRUE if @string is a key
  *
  * Checks if @string is a valid dconf key.  dconf keys must start with
  * '/', not contain '//' and not end with '/'.
@@ -138,6 +138,8 @@ dconf_is_path (const gchar  *string,
  * "/a", "/a/b" and "/a/b/c" are examples of keys.  "", "/", "a", "a/b",
  * "//a/b", "/a//b", and "/a/" are examples of strings that are not
  * keys.
+ *
+ * Returns: %TRUE if @string is a key
  **/
 gboolean
 dconf_is_key (const gchar *string,
@@ -152,7 +154,6 @@ dconf_is_key (const gchar *string,
  * dconf_is_dir:
  * @string: a string
  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
- * Returns: %TRUE if @string is a dir
  *
  * Checks if @string is a valid dconf dir.  dconf dirs must start and
  * end with '/' and not contain '//'.
@@ -164,6 +165,8 @@ dconf_is_key (const gchar *string,
  * "/", "/a/" and "/a/b/" are examples of dirs.  "", "a/", "a/b/",
  * "//a/b/", "/a//b/" and "/a" are examples of strings that are not
  * dirs.
+ *
+ * Returns: %TRUE if @string is a dir
  **/
 gboolean
 dconf_is_dir (const gchar  *string,
@@ -175,10 +178,9 @@ dconf_is_dir (const gchar  *string,
 }
 
 /**
- * dconf_is_rel:
+ * dconf_is_rel_path:
  * @string: a string
  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
- * Returns: %TRUE if @string is a relative path
  *
  * Checks if @string is a valid dconf relative path.  A relative path is
  * a string that, when concatenated to a dir, forms a valid dconf path.
@@ -186,10 +188,12 @@ dconf_is_dir (const gchar  *string,
  *
  * A dconf rel may be either a relative key or a relative dir.  See
  * dconf_is_rel_key() and dconf_is_rel_dir() for examples of each.
+ *
+ * Returns: %TRUE if @string is a relative path
  **/
 gboolean
-dconf_is_rel (const gchar  *string,
-              GError      **error)
+dconf_is_rel_path (const gchar  *string,
+                   GError      **error)
 {
 #define type "relative path"
   vars; nonnull; relative; no_double_slash; path;
@@ -201,7 +205,6 @@ dconf_is_rel (const gchar  *string,
  * dconf_is_rel_key:
  * @string: a string
  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
- * Returns: %TRUE if @string is a relative key
  *
  * Checks if @string is a valid dconf relative key.  A relative key is a
  * string that, when concatenated to a dir, forms a valid dconf key.
@@ -211,6 +214,8 @@ dconf_is_rel (const gchar  *string,
  * "a", "a/b" and "a/b/c" are examples of relative keys.  "", "/", "/a",
  * "/a/b", "//a/b", "/a//b", and "a/" are examples of strings that are
  * not relative keys.
+ *
+ * Returns: %TRUE if @string is a relative key
  **/
 gboolean
 dconf_is_rel_key (const gchar  *string,
@@ -225,7 +230,6 @@ dconf_is_rel_key (const gchar  *string,
  * dconf_is_rel_dir:
  * @string: a string
  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
- * Returns: %TRUE if @string is a relative dir
  *
  * Checks if @string is a valid dconf relative dir.  A relative dir is a
  * string that, when appended to a dir, forms a valid dconf dir.  This
@@ -237,6 +241,8 @@ dconf_is_rel_key (const gchar  *string,
  * "", "a/" and "a/b/" are examples of relative dirs.  "/", "/a/",
  * "/a/b/", "//a/b/", "a//b/" and "a" are examples of strings that are
  * not relative dirs.
+ *
+ * Returns: %TRUE if @string is a relative dir
  **/
 gboolean
 dconf_is_rel_dir (const gchar  *string,
diff --git a/common/dconf-paths.h b/common/dconf-paths.h
index fa4d1e9..48e2182 100644
--- a/common/dconf-paths.h
+++ b/common/dconf-paths.h
@@ -32,7 +32,7 @@ gboolean                dconf_is_key                                    (const g
 gboolean                dconf_is_dir                                    (const gchar         *string,
                                                                          GError             **error);
 
-gboolean                dconf_is_rel                                    (const gchar         *string,
+gboolean                dconf_is_rel_path                               (const gchar         *string,
                                                                          GError             **error);
 gboolean                dconf_is_rel_key                                (const gchar         *string,
                                                                          GError             **error);
diff --git a/docs/Makefile.am b/docs/Makefile.am
index cf13ffc..2f83c10 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -12,15 +12,3 @@ MKDB_OPTIONS = --output-format=xml
 
 INCLUDES = $(gio_CFLAGS)
 GTKDOC_LIBS = $(gio_LIBS) -L../client -ldconf -Wl,-rpath=../client
-
-IGNORE_HFILES = \
-	dconf-engine.h		\
-	dconf-shmdir.h		\
-	dconf-resetlist.h	\
-	dconf-readtype.h	\
-	dconf-rebuilder.h	\
-	gvdb-builder.h		\
-	gvdb-reader.h		\
-	gvdb-format.h
-
-
diff --git a/docs/dconf-docs.xml b/docs/dconf-docs.xml
index 31df0b3..0def819 100644
--- a/docs/dconf-docs.xml
+++ b/docs/dconf-docs.xml
@@ -12,18 +12,21 @@
   <chapter>
     <title>DConf Client API</title>
     <xi:include href='xml/paths.xml'/>
+    <xi:include href='xml/changeset.xml'/>
     <xi:include href='xml/client.xml'/>
   </chapter>
 
   <chapter id='object-tree'>
     <title>Object Hierarchy</title>
      <xi:include href='xml/tree_index.sgml'/>
+     <xi:include href='xml/object_index.sgml'/>
   </chapter>
 
   <index id='api-index-full'>
     <title>API Index</title>
     <xi:include href='xml/api-index-full.xml'><xi:fallback /></xi:include>
+    <xi:include href='xml/api-index-deprecated.xml'><xi:fallback /></xi:include>
   </index>
 
-  <xi:include href='xml/annotation-glossary.xml'><xi:fallback /></xi:include>
+  <xi:include href='xml/annotation-glossary.xml'/>
 </book>
diff --git a/docs/dconf-sections.txt b/docs/dconf-sections.txt
index 7867ddf..693ecbc 100644
--- a/docs/dconf-sections.txt
+++ b/docs/dconf-sections.txt
@@ -1,23 +1,18 @@
 <SECTION>
 <FILE>client</FILE>
 DConfClient
-DConfWatchFunc
 dconf_client_new
 dconf_client_read
-dconf_client_read_default
-dconf_client_read_no_default
 dconf_client_list
 dconf_client_is_writable
-dconf_client_write
-dconf_client_write_async
-dconf_client_write_finish
-dconf_client_write_many
-dconf_client_watch
-dconf_client_watch_async
-dconf_client_watch_finish
-dconf_client_unwatch
-dconf_client_unwatch_async
-dconf_client_unwatch_finish
+dconf_client_write_fast
+dconf_client_write_sync
+dconf_client_change_fast
+dconf_client_change_sync
+dconf_client_watch_fast
+dconf_client_watch_sync
+dconf_client_unwatch_fast
+dconf_client_unwatch_sync
 <SUBSECTION Standard>
 DConfClientClass
 DCONF_CLIENT
@@ -31,7 +26,24 @@ dconf_client_get_type
 dconf_is_dir
 dconf_is_key
 dconf_is_path
-dconf_is_rel
+dconf_is_rel_path
 dconf_is_rel_dir
 dconf_is_rel_key
 </SECTION>
+
+<SECTION>
+<FILE>changeset</FILE>
+DConfChangeset
+DConfChangesetPredicate
+dconf_changeset_all
+dconf_changeset_describe
+dconf_changeset_deserialise
+dconf_changeset_get
+dconf_changeset_is_similar_to
+dconf_changeset_new
+dconf_changeset_new_write
+dconf_changeset_ref
+dconf_changeset_serialise
+dconf_changeset_set
+dconf_changeset_unref
+</SECTION>
diff --git a/tests/paths.c b/tests/paths.c
index 57eede2..5774333 100644
--- a/tests/paths.c
+++ b/tests/paths.c
@@ -76,12 +76,12 @@ test_paths (void)
       const gchar *string = cases[i].string;
       guint flags;
 
-      flags = (dconf_is_path    (string, NULL) ? 001 : 000) |
-              (dconf_is_key     (string, NULL) ? 002 : 000) |
-              (dconf_is_dir     (string, NULL) ? 004 : 000) |
-              (dconf_is_rel     (string, NULL) ? 010 : 000) |
-              (dconf_is_rel_key (string, NULL) ? 020 : 000) |
-              (dconf_is_rel_dir (string, NULL) ? 040 : 000);
+      flags = (dconf_is_path     (string, NULL) ? 001 : 000) |
+              (dconf_is_key      (string, NULL) ? 002 : 000) |
+              (dconf_is_dir      (string, NULL) ? 004 : 000) |
+              (dconf_is_rel_path (string, NULL) ? 010 : 000) |
+              (dconf_is_rel_key  (string, NULL) ? 020 : 000) |
+              (dconf_is_rel_dir  (string, NULL) ? 040 : 000);
 
       g_assert_cmphex (flags, ==, cases[i].flags);
     }