set_lock -> set_locked and cleanup gtk-doc

Rename set_lock to set_locked again (and same SetLock -> SetLocked).

Add missing gtk-doc bits, clean up some that are no longer there.

Bump gtk-doc dependency.

4 files changed, 130 insertions, 9 deletions

diff --git a/client/Makefile.am b/client/Makefile.am
index 45e7e6f..9d716ce 100644
--- a/client/Makefile.am
+++ b/client/Makefile.am
@@ -46,7 +46,7 @@ EXTRA_DIST = dconf.vapi
 dconf.vapi: libdconf.so.0
 
 dconf.deps:
-	echo gio-2.0 > dconf.deps
+	$(AM_V_GEN) echo gio-2.0 > dconf.deps
 
 vapi_DATA = dconf.vapi dconf.deps
 vapidir = $(datadir)/vala/vapi
diff --git a/client/dconf-client.h b/client/dconf-client.h
index 137fe18..9dca7b2 100644
--- a/client/dconf-client.h
+++ b/client/dconf-client.h
@@ -79,18 +79,18 @@ gboolean                dconf_client_write_finish                       (DConfCl
                                                                          gchar               **tag,
                                                                          GError              **error);
 
-gboolean                dconf_client_set_lock                           (DConfClient          *client,
+gboolean                dconf_client_set_locked                         (DConfClient          *client,
                                                                          const gchar          *path,
                                                                          gboolean              locked,
                                                                          GCancellable         *cancellable,
                                                                          GError              **error);
-void                    dconf_client_set_lock_async                     (DConfClient          *client,
+void                    dconf_client_set_locked_async                   (DConfClient          *client,
                                                                          const gchar          *path,
                                                                          gboolean              locked,
                                                                          GCancellable         *cancellable,
                                                                          GAsyncReadyCallback   callback,
                                                                          gpointer              user_data);
-gboolean                dconf_client_set_lock_finish                    (DConfClient          *client,
+gboolean                dconf_client_set_locked_finish                  (DConfClient          *client,
                                                                          GAsyncResult         *result,
                                                                          GError              **error);
 
diff --git a/client/dconf-client.vala b/client/dconf-client.vala
index 5db8767..b929241 100644
--- a/client/dconf-client.vala
+++ b/client/dconf-client.vala
@@ -58,6 +58,24 @@ namespace DConf {
 			}
 		}
 
+		/**
+		 * dconf_client_write:
+		 * @client: a #DConfClient
+		 * @key: a dconf key
+		 * @value: (allow-none): a #GVariant, or %NULL
+		 * @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 a 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.
+		 *
+		 * 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 (string key, Variant? value, out string tag = null, Cancellable? cancellable = null) throws Error {
 			if (&tag == null) { /* bgo #591673 */
 				string junk;
@@ -68,33 +86,121 @@ namespace DConf {
 			return true;
 		}
 
+		/**
+		 * dconf_client_write_async:
+		 * @client: a #DConfClient
+		 * @key: a dconf key
+		 * @value: (allow-none): a #GVariant, or %NULL
+		 * @cancellable: a #GCancellable, or %NULL
+		 * @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.
+		 *
+		 * This is the asynchronous version of dconf_client_write().  You should call
+		 * dconf_client_write_finish() from @callback to collect the result.
+		 **/
 		public async bool write_async (string key, Variant? value, out string tag = null, Cancellable? cancellable = null) throws Error {
 			yield call_async (engine.write (key, value), out tag, cancellable);
 			return true;
 		}
 
-		public bool set_lock (string key, bool locked, Cancellable? cancellable = null) throws Error {
-			call_sync (engine.set_lock (key, locked), null, cancellable);
+		/**
+		 * 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
+		 *
+		 * Marks a dconf path as being locked.
+		 *
+		 * Locks do not affect writes to this #DConfClient.  You can still write to a key that is marked as
+		 * being locked without problems.
+		 *
+		 * Locks are only effective when they are set on a database that is being used as the source of
+		 * default/mandatory values.  In that case, the lock will prevent writes from occuring to the database
+		 * that has this database as its defaults.
+		 **/
+		public bool set_locked (string path, bool locked, Cancellable? cancellable = null) throws Error {
+			call_sync (engine.set_locked (path, locked), null, cancellable);
 			return true;
 		}
 
-		public async bool set_lock_async (string key, bool locked, Cancellable? cancellable = null) throws Error {
-			yield call_async (engine.set_lock (key, locked), null, cancellable);
+		/**
+		 * dconf_client_set_locked_async:
+		 * @client: a #DConfClient
+		 * @path: a dconf path
+		 * @locked: %TRUE to lock, %FALSE to unlock
+		 * @cancellable: a #GCancellable, or %NULL
+		 * @callback: the function to call when complete
+		 * @user_data: the user data for @callback
+		 *
+		 * 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.
+		 **/
+		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);
 			return true;
 		}
 
+		/**
+		 * @client: a #DConfClient
+		 * @key: a valid dconf key
+		 * @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);
 		}
 
+		/**
+		 * 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
+		 *
+		 * 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.
+		 **/
 		public Variant? read_default (string key) {
 			return engine.read_default (key);
 		}
 
+		/**
+		 * 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
+		 *
+		 * 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
+		 * tweaking utilities to have access to this information.
+		 *
+		 * Note that in the case of mandatory keys, the result of dconf_client_read_no_default() with a fallback
+		 * to dconf_client_read_default() is not necessarily the same as the result of a dconf_client_read().
+		 * This is because the user may have set a value before the key became marked as mandatory, in which
+		 * case this call will see the user's (otherwise inaccessible) key.
+		 **/
 		public Variant? read_no_default (string key) {
 			return engine.read_no_default (key);
 		}
 
+		/**
+		 * dconf_client_list:
+		 * @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
+		 *
+		 * Lists the keys and dirs located directly below @dir.
+		 *
+		 * You should free the return result with g_strfreev() when it is no longer needed.
+		 **/
 		public string[] list (string dir) {
 			return engine.list (dir);
 		}
@@ -130,6 +236,21 @@ namespace DConf {
 			}
 		}
 
+		/**
+		 * dconf_client_new:
+		 * @profile: the dconf profile to use, or %NULL
+		 * @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
+		 *
+		 * Creates a new #DConfClient for the given context.
+		 *
+		 * If @profile is non-%NULL then it specifies the name of the profile to use.  If @profile is %NULL then
+		 * the DCONF_PROFILE environment variable is consulted.  If that is unset then the default profile of
+		 * "user" is used.  If a profile named "user" is not installed then the dconf client is setup to access
+		 * ~/.config/dconf/user.
+		 **/
 		public Client (string? profile = null, owned WatchFunc? watch_func = null) {
 			Engine.set_service_func (service_func);
 
diff --git a/client/engine.vapi b/client/engine.vapi
index b0a6909..bf955c5 100644
--- a/client/engine.vapi
+++ b/client/engine.vapi
@@ -7,7 +7,7 @@ namespace DConf {
 		internal GLib.Variant? read (string key);
 		internal GLib.Variant? read_default (string key);
 		internal GLib.Variant? read_no_default (string key);
-		internal EngineMessage set_lock (string key, bool locked);
+		internal EngineMessage set_locked (string key, bool locked);
 		internal string[] list (string dir, void*junk = null);
 		internal static void set_service_func (ServiceFunc func);
 		internal EngineMessage watch (string name);