More cleanups and gtk-doc fill-in

12 files changed, 268 insertions, 47 deletions

diff --git a/client/.gitignore b/client/.gitignore
index 241653e..bb66dd5 100644
--- a/client/.gitignore
+++ b/client/.gitignore
@@ -1,5 +1,5 @@
 dconf.vapi
-*.c
+dconf-client.c
 *.stamp
 *.deps
 libdconf.so
diff --git a/client/Makefile.am b/client/Makefile.am
index 9d716ce..c661a52 100644
--- a/client/Makefile.am
+++ b/client/Makefile.am
@@ -42,7 +42,7 @@ libdconf_so_0_SOURCES = \
 	dconf-client.vala engine.vapi
 libdconf_so_0_VALAFLAGS = --library dconf --pkg=gio-2.0
 
-EXTRA_DIST = dconf.vapi
+EXTRA_DIST = dconf.vapi extra-docs.c
 dconf.vapi: libdconf.so.0
 
 dconf.deps:
diff --git a/client/dconf-client.h b/client/dconf-client.h
index 9dca7b2..019bb38 100644
--- a/client/dconf-client.h
+++ b/client/dconf-client.h
@@ -59,8 +59,7 @@ gchar **                dconf_client_list                               (DConfCl
                                                                          gint                 *length);
 
 gboolean                dconf_client_is_writable                        (DConfClient          *client,
-                                                                         const gchar          *key,
-                                                                         GError              **error);
+                                                                         const gchar          *key);
 
 gboolean                dconf_client_write                              (DConfClient          *client,
                                                                          const gchar          *key,
@@ -95,32 +94,34 @@ gboolean                dconf_client_set_locked_finish                  (DConfCl
                                                                          GError              **error);
 
 gboolean                dconf_client_write_many                         (DConfClient          *client,
-                                                                         const gchar          *prefix,
-                                                                         const gchar * const  *keys,
+                                                                         const gchar          *dir,
+                                                                         const gchar * const  *rels,
                                                                          GVariant            **values,
-                                                                         gsize                 n_values,
+                                                                         gint                  n_values,
                                                                          gchar               **tag,
                                                                          GCancellable         *cancellable,
                                                                          GError              **error);
+
+/* write_many_async currently disabled due to missing Vala functionality
 void                    dconf_client_write_many_async                   (DConfClient          *client,
-                                                                         const gchar          *prefix,
-                                                                         const gchar * const  *keys,
+                                                                         const gchar          *dir,
+                                                                         const gchar * const  *rels,
                                                                          GVariant            **values,
-                                                                         gsize                 n_values,
+                                                                         gint                  n_values,
                                                                          GCancellable         *cancellable,
                                                                          GAsyncReadyCallback   callback,
                                                                          gpointer              user_data);
 gboolean                dconf_client_write_many_finish                  (DConfClient          *client,
                                                                          GAsyncResult         *result,
                                                                          gchar               **tag,
-                                                                         GError              **error);
+                                                                         GError              **error);*/
 
 gboolean                dconf_client_watch                              (DConfClient          *client,
-                                                                         const gchar          *name,
+                                                                         const gchar          *path,
                                                                          GCancellable         *cancellable,
                                                                          GError              **error);
 void                    dconf_client_watch_async                        (DConfClient          *client,
-                                                                         const gchar          *name,
+                                                                         const gchar          *path,
                                                                          GCancellable         *cancellable,
                                                                          GAsyncReadyCallback   callback,
                                                                          gpointer              user_data);
@@ -128,11 +129,11 @@ gboolean                dconf_client_watch_finish                       (DConfCl
                                                                          GAsyncResult         *result,
                                                                          GError              **error);
 gboolean                dconf_client_unwatch                            (DConfClient          *client,
-                                                                         const gchar          *name,
+                                                                         const gchar          *path,
                                                                          GCancellable         *cancellable,
                                                                          GError              **error);
 void                    dconf_client_unwatch_async                      (DConfClient          *client,
-                                                                         const gchar          *name,
+                                                                         const gchar          *path,
                                                                          GCancellable         *cancellable,
                                                                          GAsyncReadyCallback   callback,
                                                                          gpointer              user_data);
diff --git a/client/dconf-client.vala b/client/dconf-client.vala
index b929241..2be8be9 100644
--- a/client/dconf-client.vala
+++ b/client/dconf-client.vala
@@ -59,6 +59,22 @@ namespace DConf {
 		}
 
 		/**
+		 * dconf_client_is_writable:
+		 * @client: a #DConfClient
+		 * @key: a dconf key
+		 * Returns: %TRUE is @key is writable
+		 *
+		 * Checks if @key is writable (ie: the key has no mandatory setting).
+		 *
+		 * This call does not verify that writing to the key will actually be successful.  It only checks for
+		 * the existence of mandatory keys/locks that might affect writing to @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.
+		 **/
+		public bool is_writable (string key) {
+			return engine.is_writable (key);
+		}
+
+		/**
 		 * dconf_client_write:
 		 * @client: a #DConfClient
 		 * @key: a dconf key
@@ -66,7 +82,7 @@ namespace DConf {
 		 * @tag: (out) (allow-none): the tag from this write
 		 * @cancellable: a #GCancellable, or %NULL
 		 * @error: a pointer to a #GError, or %NULL
-		 * @returns: %TRUE if the write is successful
+		 * Returns: %TRUE if the write is successful
 		 *
 		 * Write a value to the given @key, or reset @key to its default value.
 		 *
@@ -95,7 +111,7 @@ namespace DConf {
 		 * @callback: the function to call when complete
 		 * @user_data: the user data for @callback
 		 *
-		 * Writes a value to the given @key, or reset @key to its default value.
+		 * Write a value to the given @key, or reset @key to its default value.
 		 *
 		 * This is the asynchronous version of dconf_client_write().  You should call
 		 * dconf_client_write_finish() from @callback to collect the result.
@@ -106,13 +122,65 @@ namespace DConf {
 		}
 
 		/**
+		 * dconf_client_write_many:
+		 * @client: a #DConfClient
+		 * @dir: the dconf directory under which to make the writes
+		 * @rels: a %NULL-terminated array of relative keys
+		 * @values: an array of possibly-%NULL #GVariant pointers
+		 * @n_values: the length of @values, which must be equal to the length of @rels
+		 * @tag: (out) (allow-none): the tag from this write
+		 * @cancellable: a #GCancellable, or %NULL
+		 * @error: a pointer to a #GError, or %NULL
+		 * Returns: %TRUE if the write is successful
+		 *
+		 * Write multiple values at once.
+		 *
+		 * For each pair of items from @rels and @values, the value is written to the result of concatenating
+		 * @dir with the relative path.  As with dconf_client_write(), if a given value is %NULL then the effect
+		 * is that the specified key is reset.
+		 *
+		 * If @tag is non-%NULL then it is set to the unique tag associated with this write.  This is the same
+		 * tag that appears in change notifications.
+		 **/
+		public bool write_many (string dir, [CCode (array_length = false, array_null_terminated = true)] string[] rels, Variant?[] values, out string? tag = null, Cancellable? cancellable = null) throws Error {
+			if (&tag == null) { /* bgo #591673 */
+				string junk;
+				call_sync (engine.write_many (dir, rels, values), out junk, cancellable);
+			} else {
+				call_sync (engine.write_many (dir, rels, values), out tag, cancellable);
+			}
+			return true;
+		}
+
+		/*< disabled due to Vala compiler bugs >
+		 * dconf_client_write_many_async:
+		 * @client: a #DConfClient
+		 * @dir: the dconf directory under which to make the writes
+		 * @rels: a %NULL-terminated array of relative keys
+		 * @values: an array of possibly-%NULL #GVariant pointers
+		 * @n_values: the length of @values, which must be equal to the length of @rels
+		 * @cancellable: a #GCancellable, or %NULL
+		 * @callback: a #GAsyncReadyCallback to call when finished
+		 * @user_data: a pointer to pass as the last argument to @callback
+		 *
+		 * Write multiple values at once.
+		 *
+		 * This is the asynchronous version of dconf_client_write_many().  You should call
+		 * dconf_client_write_many_finish() from @callback to collect the result.
+		 *
+			public async bool write_many_async (string dir, [CCode (array_length = false, array_null_terminated = true)] string[] rels, Variant?[] values, out string? tag = null, Cancellable? cancellable = null) throws Error {
+			yield call_async (engine.write_many (dir, rels, values), out tag, cancellable);
+			return true;
+		}*/
+
+		/**
 		 * dconf_client_set_locked:
 		 * @client: a #DConfClient
 		 * @path: a dconf path
 		 * @locked: %TRUE to lock, %FALSE to unlock
 		 * @cancellable: a #GCancellable, or %NULL
 		 * @error: a pointer to a #GError, or %NULL
-		 * @returns: %TRUE if setting the lock was successful
+		 * Returns: %TRUE if setting the lock was successful
 		 *
 		 * Marks a dconf path as being locked.
 		 *
@@ -140,7 +208,7 @@ namespace DConf {
 		 * Marks a dconf path as being locked.
 		 *
 		 * This is the asynchronous version of dconf_client_set_locked().  You should call
-		 * dconf_client_write_finish() from @callback to collect the result.
+		 * dconf_client_set_locked_finish() from @callback to collect the result.
 		 **/
 		public async bool set_locked_async (string key, bool locked, Cancellable? cancellable = null) throws Error {
 			yield call_async (engine.set_locked (key, locked), null, cancellable);
@@ -148,12 +216,13 @@ namespace DConf {
 		}
 
 		/**
+		 * dconf_client_read:
 		 * @client: a #DConfClient
 		 * @key: a valid dconf key
-		 * @returns: the value corresponding to @key, or %NULL if there is none
+		 * Returns: the value corresponding to @key, or %NULL if there is none
 		 *
 		 * Reads the value named by @key from dconf.  If no such value exists, %NULL is returned.
-		 */
+		 **/
 		public Variant? read (string key) {
 			return engine.read (key);
 		}
@@ -162,7 +231,7 @@ namespace DConf {
 		 * dconf_client_read_default:
 		 * @client: a #DConfClient
 		 * @key: a valid dconf key
-		 * @returns: the default value corresponding to @key, or %NULL if there is none
+		 * Returns: the default value corresponding to @key, or %NULL if there is none
 		 *
 		 * Reads the value named by @key from any existing default/mandatory databases but ignoring any value
 		 * set by the user.  The result is as if the named key had just been reset.
@@ -175,7 +244,7 @@ namespace DConf {
 		 * dconf_client_read_no_default:
 		 * @client: a #DConfClient
 		 * @key: a valid dconf key
-		 * @returns: the user value corresponding to @key, or %NULL if there is none
+		 * Returns: the user value corresponding to @key, or %NULL if there is none
 		 *
 		 * Reads the value named by @key as set by the user, ignoring any default/mandatory databases.  Normal
 		 * applications will never want to do this, but it may be useful for administrative or configuration
@@ -195,7 +264,7 @@ namespace DConf {
 		 * @client: a #DConfClient
 		 * @dir: a dconf dir
 		 * @length: the number of items that were returned
-		 * @returns: (array length=length): the paths located directly below @dir
+		 * Returns: (array length=length): the paths located directly below @dir
 		 *
 		 * Lists the keys and dirs located directly below @dir.
 		 *
@@ -205,21 +274,81 @@ namespace DConf {
 			return engine.list (dir);
 		}
 
-		public bool watch (string name, Cancellable? cancellable = null) throws GLib.Error {
-			call_sync (engine.watch (name), null, cancellable);
+		/**
+		 * dconf_client_watch:
+		 * @client: a #DConfClient
+		 * @path: a dconf path
+		 * @cancellable: a #GCancellable, or %NULL
+		 * @error: a pointer to a %NULL #GError, or %NULL
+		 * Returns: %TRUE on success, else %FALSE with @error set
+		 *
+		 * Requests monitoring of a portion of the dconf database.
+		 *
+		 * If @path is a key (ie: doesn't end with a slash) then a single key is monitored for changes.  If
+		 * @path is a dir (ie: sending with a slash) then all keys that have @path as a prefix are monitored.
+		 *
+		 * This function blocks until the watch has definitely been established with the bus daemon.  If you
+		 * would like a non-blocking version of this call, see dconf_client_watch_async().
+		 **/
+		public bool watch (string path, Cancellable? cancellable = null) throws GLib.Error {
+			call_sync (engine.watch (path), null, cancellable);
 			return true;
 		}
 
+		/**
+		 * dconf_client_watch_async:
+		 * @client: a #DConfClient
+		 * @path: a dconf path
+		 * @cancellable: a #GCancellable, or %NULL
+		 * @callback: a #GAsyncReadyCallback to call when finished
+		 * @user_data: a pointer to pass as the last argument to @callback
+		 *
+		 * Requests monitoring of a portion of the dconf database.
+		 *
+		 * This is the asynchronous version of dconf_client_watch().  You should call
+		 * dconf_client_watch_finish() from @callback to collect the result.
+		 **/
 		public async bool watch_async (string name, Cancellable? cancellable = null) throws GLib.Error {
 			yield call_async (engine.watch (name), null, cancellable);
 			return true;
 		}
 
+		/**
+		 * dconf_client_unwatch:
+		 * @client: a #DConfClient
+		 * @path: a dconf path
+		 * @cancellable: a #GCancellable, or %NULL
+		 * @error: a pointer to a %NULL #GError, or %NULL
+		 * Returns: %TRUE on success, else %FALSE with @error set
+		 *
+		 * Cancels the effect of a previous call to dconf_client_watch().
+		 *
+		 * If the same path has been watched multiple times then only one of the watches is cancelled and the
+		 * net effect is that the path is still watched.
+		 *
+		 * This function blocks until the watch has definitely been removed from the bus daemon.  It is possible
+		 * that notifications in transit will arrive after this call returns.  For an asynchronous version of
+		 * this call, see dconf_client_unwatch_async().
+		 **/
 		public bool unwatch (string name, Cancellable? cancellable = null) throws GLib.Error {
 			call_sync (engine.unwatch (name), null, cancellable);
 			return true;
 		}
 
+		/**
+		 * dconf_client_unwatch_async:
+		 * @client: a #DConfClient
+		 * @path: a dconf path
+		 * @cancellable: a #GCancellable, or %NULL
+		 * @callback: a #GAsyncReadyCallback to call when finished
+		 * @user_data: a pointer to pass as the last argument to @callback
+		 *
+		 * Cancels the effect of a previous call to dconf_client_watch().
+		 *
+		 * This is the asynchronous version of dconf_client_unwatch().  You should call
+		 * dconf_client_unwatch_finish() from @callback to collect the result.  No additional notifications will
+		 * be delivered for this watch after @callback is called.
+		 **/
 		public async bool unwatch_async (string name, Cancellable? cancellable = null) throws GLib.Error {
 			yield call_async (engine.unwatch (name), null, cancellable);
 			return true;
@@ -242,7 +371,7 @@ namespace DConf {
 		 * @watch_func: the function to call when changes occur
 		 * @user_data: the user_data to pass to @watch_func
 		 * @notify: the function to free @user_data when no longer needed
-		 * @returns: a new #DConfClient
+		 * Returns: a new #DConfClient
 		 *
 		 * Creates a new #DConfClient for the given context.
 		 *
diff --git a/client/engine.vapi b/client/engine.vapi
index bf955c5..eb3e7bc 100644
--- a/client/engine.vapi
+++ b/client/engine.vapi
@@ -3,7 +3,9 @@ namespace DConf {
 	[CCode (cheader_filename = "dconf-engine.h")]
 	class Engine {
 		internal Engine (string? profile);
+		internal bool is_writable (string key);
 		internal EngineMessage write (string key, GLib.Variant? value) throws GLib.Error;
+		internal EngineMessage write_many (string dir, [CCode (array_length = false, array_null_terminated = true, type = "const gchar * const *")] string[] keys, [CCode (array_length = false)] GLib.Variant?[] values) throws GLib.Error;
 		internal GLib.Variant? read (string key);
 		internal GLib.Variant? read_default (string key);
 		internal GLib.Variant? read_no_default (string key);
diff --git a/client/extra-docs.c b/client/extra-docs.c
new file mode 100644
index 0000000..2f12951
--- /dev/null
+++ b/client/extra-docs.c
@@ -0,0 +1,89 @@
+/* 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-paths.c b/common/dconf-paths.c
index 8a63704..1278d64 100644
--- a/common/dconf-paths.c
+++ b/common/dconf-paths.c
@@ -22,6 +22,20 @@
 
 #include "dconf-paths.h"
 
+/**
+ * SECTION:paths
+ * @title: DConf Paths
+ * @short_description: utility functions to validate dconf paths
+ *
+ * Various places in the dconf API speak of "paths", "keys", "dirs" and
+ * relative versions of each of these.  This file contains functions to
+ * check if a given string is a valid member of each of these classes
+ * and to report errors when a string is not.
+ *
+ * See each function in this section for a precise description of what
+ * makes a string a valid member of a given class.
+ **/
+
 #define vars gchar c, l
 
 #define DCONF_ERROR 0
diff --git a/docs/dconf-docs.xml b/docs/dconf-docs.xml
index 4a8745c..31df0b3 100644
--- a/docs/dconf-docs.xml
+++ b/docs/dconf-docs.xml
@@ -12,7 +12,7 @@
   <chapter>
     <title>DConf Client API</title>
     <xi:include href='xml/paths.xml'/>
-    <xi:include href='xml/dconf-client.xml'/>
+    <xi:include href='xml/client.xml'/>
   </chapter>
 
   <chapter id='object-tree'>
diff --git a/docs/dconf-sections.txt b/docs/dconf-sections.txt
index ae4b1b2..475522f 100644
--- a/docs/dconf-sections.txt
+++ b/docs/dconf-sections.txt
@@ -1,6 +1,5 @@
 <SECTION>
-<FILE>dconf-client</FILE>
-DConfClientClass
+<FILE>client</FILE>
 DConfClient
 DConfWatchFunc
 dconf_client_new
@@ -16,8 +15,6 @@ dconf_client_set_locked
 dconf_client_set_locked_async
 dconf_client_set_locked_finish
 dconf_client_write_many
-dconf_client_write_many_async
-dconf_client_write_many_finish
 dconf_client_watch
 dconf_client_watch_async
 dconf_client_watch_finish
@@ -25,6 +22,7 @@ dconf_client_unwatch
 dconf_client_unwatch_async
 dconf_client_unwatch_finish
 <SUBSECTION Standard>
+DConfClientClass
 DCONF_CLIENT
 DCONF_IS_CLIENT
 DCONF_TYPE_CLIENT
diff --git a/engine/dconf-engine.c b/engine/dconf-engine.c
index 4960c4c..cf57431 100644
--- a/engine/dconf-engine.c
+++ b/engine/dconf-engine.c
@@ -466,13 +466,8 @@ dconf_engine_unwatch (DConfEngine        *engine,
 
 gboolean
 dconf_engine_is_writable (DConfEngine         *engine,
-                          const gchar         *name,
-                          DConfEngineMessage  *dcem,
-                          GError             **error)
+                          const gchar         *name)
 {
-  dcem->bus_type = 'e';
-  dcem->body = g_variant_new ("()");
-
   return TRUE;
 }
 
diff --git a/engine/dconf-engine.h b/engine/dconf-engine.h
index 5cc2a09..229c1a1 100644
--- a/engine/dconf-engine.h
+++ b/engine/dconf-engine.h
@@ -70,9 +70,7 @@ void                    dconf_engine_get_service_info                   (DConfEn
                                                                          const gchar            **destination,
                                                                          const gchar            **object_path);
 gboolean                dconf_engine_is_writable                        (DConfEngine             *engine,
-                                                                         const gchar             *name,
-                                                                         DConfEngineMessage      *message,
-                                                                         GError                 **error);
+                                                                         const gchar             *name);
 gboolean                dconf_engine_write                              (DConfEngine             *engine,
                                                                          const gchar             *key,
                                                                          GVariant                *value,
diff --git a/gsettings/dconfsettingsbackend.c b/gsettings/dconfsettingsbackend.c
index 121d52f..42db04e 100644
--- a/gsettings/dconfsettingsbackend.c
+++ b/gsettings/dconfsettingsbackend.c
@@ -495,13 +495,8 @@ dconf_settings_backend_get_writable (GSettingsBackend *backend,
                                      const gchar      *name)
 {
   DConfSettingsBackend *dcsb = (DConfSettingsBackend *) backend;
-  DConfEngineMessage dcem;
-  GDBusConnection *bus;
-
-  if (!dconf_engine_is_writable (dcsb->engine, name, &dcem, NULL))
-    return FALSE;
 
-  return dconf_settings_backend_get_bus (dcsb, &bus, &dcem);
+  return dconf_engine_is_writable (dcsb->engine, name);
 }
 
 static void