big docs cleanup

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

2 files changed, 276 insertions, 89 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().
- **/