diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index ed6b3d293..b95a0a9e2 100644
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -2,4 +2,5 @@ base64.sgml
ghostutils.sgml
gurifuncs.sgml
gvarianttype.sgml
+hash_tables.sgml
option.sgml
diff --git a/docs/reference/glib/tmpl/hash_tables.sgml b/docs/reference/glib/tmpl/hash_tables.sgml
deleted file mode 100644
index 2fa2c86ce..000000000
--- a/docs/reference/glib/tmpl/hash_tables.sgml
+++ /dev/null
@@ -1,489 +0,0 @@
-
-Hash Tables
-
-
-associations between keys and values so that given a key the value
-can be found quickly
-
-
-
-A #GHashTable provides associations between keys and values which
-is optimized so that given a key, the associated value can be found
-very quickly.
-
-
-Note that neither keys nor values are copied when inserted into the
-#GHashTable, so they must exist for the lifetime of the #GHashTable.
-This means that the use of static strings is OK, but temporary
-strings (i.e. those created in buffers and those returned by GTK+ widgets)
-should be copied with g_strdup() before being inserted.
-
-
-If keys or values are dynamically allocated, you must be careful to ensure
-that they are freed when they are removed from the #GHashTable, and also
-when they are overwritten by new insertions into the #GHashTable.
-It is also not advisable to mix static strings and dynamically-allocated
-strings in a #GHashTable, because it then becomes difficult to determine
-whether the string should be freed.
-
-
-To create a #GHashTable, use g_hash_table_new().
-
-
-To insert a key and value into a #GHashTable, use g_hash_table_insert().
-
-
-To lookup a value corresponding to a given key, use g_hash_table_lookup()
-and g_hash_table_lookup_extended().
-
-
-To remove a key and value, use g_hash_table_remove().
-
-
-To call a function for each key and value pair use g_hash_table_foreach()
-or use a iterator to iterate over the key/value pairs in the hash table, see
-#GHashTableIter.
-
-
-To destroy a #GHashTable use g_hash_table_destroy().
-
-
-
-
-
-
-
-
-
-
-
-
-The GHashTable struct is an opaque data structure to represent a
-Hash Table.
-It should only be accessed via the following functions.
-
-
-
-
-
-
-
-
-@hash_func:
-@key_equal_func:
-@Returns:
-
-
-
-
-
-
-
-@hash_func:
-@key_equal_func:
-@key_destroy_func:
-@value_destroy_func:
-@Returns:
-
-
-
-
-Specifies the type of the hash function which is passed to
-g_hash_table_new() when a #GHashTable is created.
-
-
-The function is passed a key and should return a #guint hash value.
-The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
-hash functions which can be used when the key is a #gpointer, #gint, and
-#gchar* respectively.
-
-
-
-The hash values should be evenly distributed over a fairly large range?
-The modulus is taken with the hash table size (a prime number)
-to find the 'bucket' to place each key into.
-The function should also be very fast, since it is called for each key
-lookup.
-
-
-@key: a key.
-@Returns: the hash value corresponding to the key.
-
-
-
-
-Specifies the type of a function used to test two values for
-equality. The function should return %TRUE if both values are equal and
-%FALSE otherwise.
-
-
-@a: a value.
-@b: a value to compare with.
-@Returns: %TRUE if @a = @b; %FALSE otherwise.
-
-
-
-
-
-
-
-@hash_table:
-@key:
-@value:
-
-
-
-
-
-
-
-@hash_table:
-@key:
-@value:
-
-
-
-
-
-
-
-@hash_table:
-@Returns:
-
-
-
-
-
-
-
-@hash_table:
-@key:
-@Returns:
-
-
-
-
-
-
-
-@hash_table:
-@lookup_key:
-@orig_key:
-@value:
-@Returns:
-
-
-
-
-
-
-
-@hash_table:
-@func:
-@user_data:
-
-
-
-
-
-
-
-@hash_table:
-@predicate:
-@user_data:
-@Returns:
-
-
-
-
-Specifies the type of the function passed to g_hash_table_foreach().
-It is called with each key/value pair, together with the @user_data parameter
-which is passed to g_hash_table_foreach().
-
-
-@key: a key.
-@value: the value corresponding to the key.
-@user_data: user data passed to g_hash_table_foreach().
-
-
-
-
-
-
-
-@hash_table:
-@key:
-@Returns:
-
-
-
-
-
-
-
-@hash_table:
-@key:
-@Returns:
-
-
-
-
-
-
-
-@hash_table:
-@func:
-@user_data:
-@Returns:
-
-
-
-
-
-
-
-@hash_table:
-@func:
-@user_data:
-@Returns:
-
-
-
-
-
-
-
-@hash_table:
-
-
-
-
-
-
-
-@hash_table:
-
-
-
-
-
-
-
-@hash_table:
-@Returns:
-
-
-
-
-
-
-
-@hash_table:
-@Returns:
-
-
-
-
-Specifies the type of the function passed to g_hash_table_foreach_remove().
-It is called with each key/value pair, together with the @user_data parameter
-passed to g_hash_table_foreach_remove().
-It should return %TRUE if the key/value pair should be removed from the
-#GHashTable.
-
-
-@key: a key.
-@value: the value associated with the key.
-@user_data: user data passed to g_hash_table_remove().
-@Returns: %TRUE if the key/value pair should be removed from the #GHashTable.
-
-
-
-
-This function is deprecated and will be removed in the next major
- release of GLib. It does nothing.
-
-
-@hash_table: a #GHashTable
-
-
-
-
-This function is deprecated and will be removed in the next major
- release of GLib. It does nothing.
-
-
-@hash_table: a #GHashTable
-
-
-
-
-
-
-
-@hash_table:
-
-
-
-
-
-
-
-@hash_table:
-@Returns:
-
-
-
-
-
-
-
-@hash_table:
-
-
-
-
-A GHashTableIter structure represents an iterator that can be
-used to iterate over the elements of a #GHashTable. GHashTableIter
-structures are typically allocated on the stack and then initialized
-with g_hash_table_iter_init().
-
-
-
-
-
-
-
-
-@iter:
-@hash_table:
-
-
-
-
-
-
-
-@iter:
-@key:
-@value:
-@Returns:
-
-
-
-
-
-
-
-@iter:
-@Returns:
-
-
-
-
-
-
-
-@iter:
-
-
-
-
-
-
-
-@iter:
-
-
-
-
-
-
-
-@v1:
-@v2:
-@Returns:
-
-
-
-
-
-
-
-@v:
-@Returns:
-
-
-
-
-
-
-
-@v1:
-@v2:
-@Returns:
-
-
-
-
-
-
-
-@v:
-@Returns:
-
-
-
-
-
-
-
-@v1:
-@v2:
-@Returns:
-
-
-
-
-
-
-
-@v:
-@Returns:
-
-
-
-
-
-
-
-@v1:
-@v2:
-@Returns:
-
-
-
-
-
-
-
-@v:
-@Returns:
-
-
-
-
-
-
-@v1:
-@v2:
-@Returns:
-
-
-
-
-
-
-@v:
-@Returns:
-
-
diff --git a/glib/ghash.c b/glib/ghash.c
index 820d09547..f8c29365e 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -35,6 +35,120 @@
#include "glib.h"
#include "galias.h"
+/**
+ * SECTION: hash_tables
+ * @title: Hash Tables
+ * @short_description: associations between keys and values so that
+ * given a key the value can be found quickly
+ *
+ * A #GHashTable provides associations between keys and values which is
+ * optimized so that given a key, the associated value can be found
+ * very quickly.
+ *
+ * Note that neither keys nor values are copied when inserted into the
+ * #GHashTable, so they must exist for the lifetime of the #GHashTable.
+ * This means that the use of static strings is OK, but temporary
+ * strings (i.e. those created in buffers and those returned by GTK+
+ * widgets) should be copied with g_strdup() before being inserted.
+ *
+ * If keys or values are dynamically allocated, you must be careful to
+ * ensure that they are freed when they are removed from the
+ * #GHashTable, and also when they are overwritten by new insertions
+ * into the #GHashTable. It is also not advisable to mix static strings
+ * and dynamically-allocated strings in a #GHashTable, because it then
+ * becomes difficult to determine whether the string should be freed.
+ *
+ * To create a #GHashTable, use g_hash_table_new().
+ *
+ * To insert a key and value into a #GHashTable, use
+ * g_hash_table_insert().
+ *
+ * To lookup a value corresponding to a given key, use
+ * g_hash_table_lookup() and g_hash_table_lookup_extended().
+ *
+ * To remove a key and value, use g_hash_table_remove().
+ *
+ * To call a function for each key and value pair use
+ * g_hash_table_foreach() or use a iterator to iterate over the
+ * key/value pairs in the hash table, see #GHashTableIter.
+ *
+ * To destroy a #GHashTable use g_hash_table_destroy().
+ **/
+
+/**
+ * GHashTable:
+ *
+ * The #GHashTable struct is an opaque data structure to represent a
+ * Hash Table. It should only be
+ * accessed via the following functions.
+ **/
+
+/**
+ * GHashFunc:
+ * @key: a key.
+ * @Returns: the hash value corresponding to the key.
+ *
+ * Specifies the type of the hash function which is passed to
+ * g_hash_table_new() when a #GHashTable is created.
+ *
+ * The function is passed a key and should return a #guint hash value.
+ * The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
+ * hash functions which can be used when the key is a #gpointer, #gint,
+ * and #gchar* respectively.
+ *
+ * The hash values should be evenly
+ * distributed over a fairly large range? The modulus is taken with the
+ * hash table size (a prime number) to find the 'bucket' to place each
+ * key into. The function should also be very fast, since it is called
+ * for each key lookup.
+ **/
+
+/**
+ * GHFunc:
+ * @key: a key.
+ * @value: the value corresponding to the key.
+ * @user_data: user data passed to g_hash_table_foreach().
+ *
+ * Specifies the type of the function passed to g_hash_table_foreach().
+ * It is called with each key/value pair, together with the @user_data
+ * parameter which is passed to g_hash_table_foreach().
+ **/
+
+/**
+ * GHRFunc:
+ * @key: a key.
+ * @value: the value associated with the key.
+ * @user_data: user data passed to g_hash_table_remove().
+ * @Returns: %TRUE if the key/value pair should be removed from the
+ * #GHashTable.
+ *
+ * Specifies the type of the function passed to
+ * g_hash_table_foreach_remove(). It is called with each key/value
+ * pair, together with the @user_data parameter passed to
+ * g_hash_table_foreach_remove(). It should return %TRUE if the
+ * key/value pair should be removed from the #GHashTable.
+ **/
+
+/**
+ * GEqualFunc:
+ * @a: a value.
+ * @b: a value to compare with.
+ * @Returns: %TRUE if @a = @b; %FALSE otherwise.
+ *
+ * Specifies the type of a function used to test two values for
+ * equality. The function should return %TRUE if both values are equal
+ * and %FALSE otherwise.
+ **/
+
+/**
+ * GHashTableIter:
+ *
+ * A GHashTableIter structure represents an iterator that can be used
+ * to iterate over the elements of a #GHashTable. GHashTableIter
+ * structures are typically allocated on the stack and then initialized
+ * with g_hash_table_iter_init().
+ **/
+
#define HASH_TABLE_MIN_SHIFT 3 /* 1 << 3 == 8 buckets */
typedef struct _GHashNode GHashNode;
diff --git a/glib/ghash.h b/glib/ghash.h
index 7f1e79e1f..9128721bc 100644
--- a/glib/ghash.h
+++ b/glib/ghash.h
@@ -113,9 +113,22 @@ void g_hash_table_unref (GHashTable *hash_table);
#ifndef G_DISABLE_DEPRECATED
-/* The following two functions are deprecated and will be removed in
- * the next major release. They do no good. */
+/**
+ * g_hash_table_freeze:
+ * @hash_table: a #GHashTable
+ *
+ * This function is deprecated and will be removed in the next major
+ * release of GLib. It does nothing.
+ **/
#define g_hash_table_freeze(hash_table) ((void)0)
+
+/**
+ * g_hash_table_thaw:
+ * @hash_table: a #GHashTable
+ *
+ * This function is deprecated and will be removed in the next major
+ * release of GLib. It does nothing.
+ **/
#define g_hash_table_thaw(hash_table) ((void)0)
#endif /* G_DISABLE_DEPRECATED */