[dconf] docs/comments: make some corrections/updates

[Ryan Lortie <ryanl src gnome org>]

commit 9d0b53f86371a459615e9872a5b835b917a568ae
Author: Ryan Lortie <desrt desrt ca>
Date:   Mon Feb 4 12:55:51 2013 +0100

    docs/comments: make some corrections/updates
    
    Many fixes for typos but also some adjustments for the recent
    refactoring (particularly updating HACKING).

 HACKING                  |   25 ++++++++++++++++++-------
 client/dconf-client.c    |    6 +++---
 common/dconf-changeset.c |   11 ++++++-----
 common/dconf-paths.c     |    2 +-
 engine/dconf-engine.c    |    6 +++---
 shm/dconf-shm.c          |    4 ++--
 6 files changed, 33 insertions(+), 21 deletions(-)
---
diff --git a/HACKING b/HACKING
index 64a6984..d071e03 100644
--- a/HACKING
+++ b/HACKING
@@ -13,9 +13,9 @@ gvdb/:
 
   The code is split into a reader and a writer (builder).
 
-  This directory doesn't produce any libraries.  The source files are
-  included into other libraries and executables by direct inclusion of
-  these source files into the Makefiles of other directories.
+  This directory produces two libraries: libgvdb.a and libgvdb-shared.a.
+  They are exactly the same, except that libgvdb-shared.a was compiled
+  with -fPIC.
 
 common/:
 
@@ -35,21 +35,29 @@ engine/:
   to D-Bus.  All users of the engine must therefore include a module
   that implements this glue.
 
-  This directory produces one library: libdconf-engine.a.  This library
-  includes the gvdb-reader.
+  The engine also requires gvdb.
+
+  This directory produces libdconf-engine.a and its -shared variant.
 
 gdbus/:
 
   This directory contains the glue code for dconf over GDBus.
 
-  This directory produces one library: libdconf-gdbus.a.
+  There are two implementations of this code: a threaded approach and an
+  approach based on GDBus filter functions.  The threaded one is in use
+  by default, but both are built for testing purposes.
+
+  This directory produces a library for each backend:
+  libdconf-gdbus-thread.a and libdconf-gdbus-filter.a, plus their
+  -shared variants.
 
 client/:
 
   This is the standard GObject client-side library used for direct access to
   dconf.  It uses the GDBus glue from the gdbus/ directory above.
 
-  This directory produces the libdconf.so shared library.
+  This directory produces the libdconf.so shared library as well as
+  libdconf-client.a which is used for testing.
 
 gsettings/:
 
@@ -65,6 +73,9 @@ dbus-1/:
 
   This directory produces the libdconf-dbus-1.so shared library.
 
+  It also produces libdconf-libdbus-1.a (containing the D-Bus glue) for
+  testing purposes, and its -shared variant.
+
 bin/:
 
   This is the 'dconf' commandline tool.  It uses the library from
diff --git a/client/dconf-client.c b/client/dconf-client.c
index ca84670..c7c2e9e 100644
--- a/client/dconf-client.c
+++ b/client/dconf-client.c
@@ -28,7 +28,7 @@
 /**
  * SECTION:client
  * @title: DConfClient
- * @short_description: Direct read and write access to DConf, based on GDBus
+ * @short_description: Direct read and write access to dconf, based on GDBus
  *
  * This is the primary client interface to dconf.
  *
@@ -97,7 +97,7 @@ dconf_client_class_init (DConfClientClass *class)
    *
    * 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
+   * occurred; 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
@@ -493,7 +493,7 @@ dconf_client_watch_fast (DConfClient *client,
  * 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
+ * This function submits each of 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.
  *
diff --git a/common/dconf-changeset.c b/common/dconf-changeset.c
index 639ea89..e6931b0 100644
--- a/common/dconf-changeset.c
+++ b/common/dconf-changeset.c
@@ -47,7 +47,7 @@
  * This is a reference counted opaque structure type.  It is not a
  * #GObject.
  *
- * Use dconf_changeset_ref() and dconf_changeset_unref() to manipuate
+ * Use dconf_changeset_ref() and dconf_changeset_unref() to manipulate
  * references.
  **/
 
@@ -334,7 +334,7 @@ dconf_changeset_is_similar_to (DConfChangeset *changeset,
  * @predicate is called on each item in the changeset, in turn, until it
  * returns %FALSE.
  *
- * If @preciate returns %FALSE for any item, this function returns
+ * If @predicate returns %FALSE for any item, this function returns
  * %FALSE.  If not (including the case of no items) then this function
  * returns %TRUE.
  *
@@ -387,8 +387,9 @@ dconf_changeset_build_description (DConfChangeset *changeset)
    * Next, we iterate the table again to pull the strings out excluding
    * the leading prefix.
    *
-   * We sort the list of paths at this point because the rebuilder
-   * requires a sorted list.
+   * We sort the list of paths at this point because the writer
+   * requires a sorted list in order to ensure that dir resets come
+   * before writes to keys in that dir.
    *
    * Finally, we iterate over the sorted list and use the normal
    * hashtable lookup in order to populate the values array in the same
@@ -562,7 +563,7 @@ dconf_changeset_serialise (DConfChangeset *changeset)
  * 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.
+ * that resulted from an earlier serialise operation.
  *
  * This call never fails, even if @serialised is not in the correct
  * format.  Improperly-formatted parts are simply ignored.
diff --git a/common/dconf-paths.c b/common/dconf-paths.c
index 33a6f74..70cea5b 100644
--- a/common/dconf-paths.c
+++ b/common/dconf-paths.c
@@ -24,7 +24,7 @@
 
 /**
  * SECTION:paths
- * @title: DConf Paths
+ * @title: dconf Paths
  * @short_description: utility functions to validate dconf paths
  *
  * Various places in the dconf API speak of "paths", "keys", "dirs" and
diff --git a/engine/dconf-engine.c b/engine/dconf-engine.c
index 5a7b6ac..45e1d66 100644
--- a/engine/dconf-engine.c
+++ b/engine/dconf-engine.c
@@ -141,7 +141,7 @@
  * The second lock (queue_lock) protects the various queues that are
  * used to implement the "fast" writes described above.
  *
- * If both locks are held at the same time thne the sources lock must
+ * If both locks are held at the same time then the sources lock must
  * have been acquired first.
  */
 
@@ -451,7 +451,7 @@ dconf_engine_read (DConfEngine *engine,
    *     means that no locks were found.  Non-zero means that a lock was
    *     found in the source with the index given by the variable.
    *
-   *  2. check the uncommited changes in the read_through list as the
+   *  2. check the uncommitted changes in the read_through list as the
    *     highest priority.  This is only done if we have a writable
    *     source and no locks were found.
    *
@@ -937,7 +937,7 @@ dconf_engine_change_completed (DConfEngine  *engine,
 
   if (error)
     {
-      /* Some kind of unexpected failure occured while attempting to
+      /* Some kind of unexpected failure occurred while attempting to
        * commit the change.
        *
        * There's not much we can do here except to drop our local copy
diff --git a/shm/dconf-shm.c b/shm/dconf-shm.c
index d291305..57890c6 100644
--- a/shm/dconf-shm.c
+++ b/shm/dconf-shm.c
@@ -71,7 +71,7 @@ dconf_shm_open (const gchar *name)
       goto out;
     }
 
-  /* fruncate(fd, 1) is not sufficient because it does not actually
+  /* ftruncate(fd, 1) is not sufficient because it does not actually
    * ensure that the space is available (which could give a SIGBUS
    * later).
    *
@@ -128,7 +128,7 @@ dconf_shm_flag (const gchar *name)
         {
           guint8 *shm;
 
-          /* It would ahve been easier for us to do write(fd, "\1", 1);
+          /* It would have been easier for us to do write(fd, "\1", 1);
            * but this causes problems on kernels (ie: OpenBSD) that
            * don't sync up their filesystem cache with mmap()ed regions.
            *