[glib/gvdb] GHashFile fixes

[Ryan Lortie <ryanl src gnome org>]

commit 28d427fa28ee4ede8def3cc32204a9984bf7270e
Author: Ryan Lortie <desrt desrt ca>
Date:   Mon Apr 12 17:58:35 2010 -0400

    GHashFile fixes

 glib/ghashfile.c |   93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 93 insertions(+), 0 deletions(-)
---
diff --git a/glib/ghashfile.c b/glib/ghashfile.c
index 6922844..2edcf54 100644
--- a/glib/ghashfile.c
+++ b/glib/ghashfile.c
@@ -124,6 +124,26 @@ g_hash_file_setup_root (GHashFile                 *file,
   file->n_hash_items = size / sizeof (struct gvdb_hash_item);
 }
 
+/**
+ * g_hash_file_new:
+ * @filename: the path to the hash file
+ * @trusted: if the contents of @filename are trusted
+ * @error: %NULL, or a pointer to a %NULL #GError
+ * @returns: a new #GHashFile
+ *
+ * Creates a new #GHashFile from the contents of the file found at
+ * @filename.
+ *
+ * The only time this function fails is if the file can not be opened.
+ * In that case, the #GError that is returned will be an error from
+ * g_mapped_file_new().
+ *
+ * An empty or otherwise corrupted file is considered to be a valid
+ * #GHashFile with no entries.
+ *
+ * You should call g_hash_file_unref() on the return result when you no
+ * longer require it.
+ **/
 GHashFile *
 g_hash_file_new (const gchar  *filename,
                  gboolean      trusted,
@@ -138,6 +158,7 @@ g_hash_file_new (const gchar  *filename,
   file = g_slice_new0 (GHashFile);
   file->data = g_mapped_file_get_contents (mapped);
   file->size = g_mapped_file_get_length (mapped);
+  file->trusted = trusted;
   file->mapped = mapped;
   file->ref_count = 1;
 
@@ -237,6 +258,24 @@ g_hash_file_lookup (GHashFile   *file,
   return NULL;
 }
 
+/**
+ * g_hash_file_list:
+ * @file: a #GHashFile
+ * @key: a string
+ * @returns: a %NULL-terminated string array
+ *
+ * List all of the keys that appear below @key.  The nesting of keys
+ * within the hash file is defined by the program that created the hash
+ * file.  One thing is constant: each item in the returned array can be
+ * concatenated to @key to obtain the full name of that key.
+ *
+ * It is not possible to tell from this function if a given key is
+ * itself a path, a value, or another hash table; you are expected to
+ * know this for yourself.
+ *
+ * You should call g_strfreev() on the return result when you no longer
+ * require it.
+ **/
 gchar **
 g_hash_file_list (GHashFile   *file,
                   const gchar *key)
@@ -286,6 +325,26 @@ g_hash_file_list (GHashFile   *file,
   return strv;
 }
 
+/**
+ * g_hash_file_get_value:
+ * @file: a #GHashFile
+ * @key: a string
+ * @options: a pointer to a #GVariant, or %NULL
+ * @returns: a #GVariant, or %NULL
+ *
+ * Looks up a value named @key in @file.
+ *
+ * If the value is not found then %NULL is returned.  Otherwise, a new
+ * #GVariant instance is returned.  The #GVariant does not depend on the
+ * continued existence of @file.
+ *
+ * If @options is non-%NULL then it will be set either to %NULL in the
+ * case of no options or a #GVariant containing a dictionary mapping
+ * strings to variants.
+ *
+ * You should call g_variant_unref() on the return result when you no
+ * longer require it.
+ **/
 GVariant *
 g_hash_file_get_value (GHashFile    *file,
                        const gchar  *key,
@@ -330,6 +389,25 @@ g_hash_file_get_value (GHashFile    *file,
   return value;
 }
 
+/**
+ * g_hash_file_get_hash:
+ * @file: a #GHashFile
+ * @key: a string
+ * @returns: a new #GHashFile, or %NULL
+ *
+ * Looks up the hash table named @key in @file.
+ *
+ * The toplevel hash table in a #GHashFile can contain reference to
+ * child hash tables (and those can contain further references...).
+ *
+ * If @key is not found in @file then %NULL is returned.  Otherwise, a
+ * new #GHashFile is returned, referring to the child hashtable as
+ * contained in the file.  This newly-created #GHashFile does not depend
+ * on the continued existence of @file.
+ *
+ * You should call g_hash_file_unref() on the return result when you no
+ * longer require it.
+ **/
 GHashFile *
 g_hash_file_get_hash (GHashFile   *file,
                       const gchar *key)
@@ -354,6 +432,13 @@ g_hash_file_get_hash (GHashFile   *file,
   return new;
 }
 
+/**
+ * g_hash_file_ref:
+ * @file: a #GHashFile
+ * @returns: a new reference on @file
+ *
+ * Increases the reference count on @file.
+ **/
 GHashFile *
 g_hash_file_ref (GHashFile *file)
 {
@@ -362,6 +447,14 @@ g_hash_file_ref (GHashFile *file)
   return file;
 }
 
+/**
+ * g_hash_file_unref:
+ * @file: a #GHashFile
+ *
+ * Decreases the reference count on @file, possibly freeing it.
+ *
+ * Since: 2.26
+ **/
 void
 g_hash_file_unref (GHashFile *file)
 {