GRelation: move docs from tmpl to .c

diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index da42f15..12d1162 100644 (file)
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -14,6 +14,7 @@ option.sgml
 patterns.sgml 
 quarks.sgml
 random_numbers.sgml
+relations.sgml
 sequence.sgml
 shell.sgml
 string_chunks.sgml

diff --git a/docs/reference/glib/tmpl/relations.sgml b/docs/reference/glib/tmpl/relations.sgml
deleted file mode 100644 (file)
index 33f279f..0000000
--- a/docs/reference/glib/tmpl/relations.sgml
+++ /dev/null
@@ -1,204 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-Relations and Tuples
-
-<!-- ##### SECTION Short_Description ##### -->
-tables of data which can be indexed on any number of fields
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-A #GRelation is a table of data which can be indexed on any number of fields,
-rather like simple database tables. A #GRelation contains a number of
-records, called tuples. Each record contains a number of fields.
-Records are not ordered, so it is not possible to find the record at a
-particular index.
-</para>
-<para>
-Note that #GRelation tables are currently limited to 2 fields.
-</para>
-<para>
-To create a GRelation, use g_relation_new().
-</para>
-<para>
-To specify which fields should be indexed, use g_relation_index().
-Note that this must be called before any tuples are added to the #GRelation.
-</para>
-<para>
-To add records to a #GRelation use g_relation_insert().
-</para>
-<para>
-To determine if a given record appears in a #GRelation, use
-g_relation_exists(). Note that fields are compared directly, so pointers
-must point to the exact same position (i.e. different copies of the same
-string will not match.)
-</para>
-<para>
-To count the number of records which have a particular value in a given
-field, use g_relation_count().
-</para>
-<para>
-To get all the records which have a particular value in a given field,
-use g_relation_select(). To access fields of the resulting records,
-use g_tuples_index(). To free the resulting records use g_tuples_destroy().
-</para>
-<para>
-To delete all records which have a particular value in a given field,
-use g_relation_delete().
-</para>
-<para>
-To destroy the #GRelation, use g_relation_destroy().
-</para>
-<para>
-To help debug #GRelation objects, use g_relation_print().
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GRelation ##### -->
-<para>
-The #GRelation struct is an opaque data structure to represent a
-<link linkend="glib-Relations-and-Tuples">Relation</link>.
-It should only be accessed via the following functions.
-</para>
-
-
-<!-- ##### FUNCTION g_relation_new ##### -->
-<para>
-Creates a new #GRelation with the given number of fields.
-Note that currently the number of fields must be 2.
-</para>
-
-@fields: the number of fields.
-@Returns: a new #GRelation.
-
-
-<!-- ##### FUNCTION g_relation_index ##### -->
-<para>
-Creates an index on the given field.
-Note that this must be called before any records are added to the #GRelation.
-</para>
-
-@relation: a #GRelation.
-@field: the field to index, counting from 0.
-@hash_func: a function to produce a hash value from the field data.
-@key_equal_func: a function to compare two values of the given field.
-
-
-<!-- ##### FUNCTION g_relation_insert ##### -->
-<para>
-Inserts a record into a #GRelation.
-</para>
-
-@relation: a #GRelation.
-@Varargs: the fields of the record to add. These must match the number of
-fields in the #GRelation, and of type #gpointer or #gconstpointer.
-
-
-<!-- ##### FUNCTION g_relation_exists ##### -->
-<para>
-Returns %TRUE if a record with the given values exists in a #GRelation.
-Note that the values are compared directly, so that, for example, two
-copies of the same string will not match.
-</para>
-
-@relation: a #GRelation.
-@Varargs: the fields of the record to compare. The number must match the
-number of fields in the #GRelation.
-@Returns: %TRUE if a record matches.
-
-
-<!-- ##### FUNCTION g_relation_count ##### -->
-<para>
-Returns the number of tuples in a #GRelation that have the given value
-in the given field.
-</para>
-
-@relation: a #GRelation.
-@key: the value to compare with.
-@field: the field of each record to match.
-@Returns: the number of matches.
-
-
-<!-- ##### FUNCTION g_relation_select ##### -->
-<para>
-Returns all of the tuples which have the given key in the given field.
-Use g_tuples_index() to access the returned records.
-The returned records should be freed with g_tuples_destroy().
-</para>
-
-@relation: a #GRelation.
-@key: the value to compare with.
-@field: the field of each record to match.
-@Returns: the records (tuples) that matched.
-
-
-<!-- ##### FUNCTION g_relation_delete ##### -->
-<para>
-Deletes any records from a #GRelation that have the given key value in
-the given field.
-</para>
-
-@relation: a #GRelation.
-@key: the value to compare with.
-@field: the field of each record to match.
-@Returns: the number of records deleted.
-
-
-<!-- ##### FUNCTION g_relation_destroy ##### -->
-<para>
-Destroys the #GRelation, freeing all memory allocated.
-However, it does not free memory allocated for the
-tuple data, so you should free that first if appropriate.
-</para>
-
-@relation: a #GRelation.
-
-
-<!-- ##### FUNCTION g_relation_print ##### -->
-<para>
-Outputs information about all records in a #GRelation, as well as the indexes.
-It is for debugging.
-</para>
-
-@relation: a #GRelation.
-
-
-<!-- ##### STRUCT GTuples ##### -->
-<para>
-The #GTuples struct is used to return records (or tuples) from the
-#GRelation by g_relation_select().
-It only contains one public member - the number of records that matched.
-To access the matched records, you must use g_tuples_index().
-</para>
-
-@len: the number of records that matched.
-
-<!-- ##### FUNCTION g_tuples_destroy ##### -->
-<para>
-Frees the records which were returned by g_relation_select().
-This should always be called after g_relation_select() when you are
-finished with the records.
-The records are not removed from the #GRelation.
-</para>
-
-@tuples: the tuple data to free.
-
-
-<!-- ##### FUNCTION g_tuples_index ##### -->
-<para>
-Gets a field from the records returned by g_relation_select().
-It returns the given field of the record at the given index.
-The returned value should not be changed.
-</para>
-
-@tuples: the tuple data, returned by g_relation_select().
-@index_: the index of the record.
-@field: the field to return.
-@Returns: the field of the record.
-
-

diff --git a/glib/grel.c b/glib/grel.c
index b6ee651..8cecd29 100644 (file)
--- a/glib/grel.c
+++ b/glib/grel.c
@@ -35,9 +35,58 @@
 #include "glib.h"
 #include "galias.h"
 
+/**
+ * SECTION: relations
+ * @title: Relations and Tuples
+ * @short_description: tables of data which can be indexed on any
+ *                     number of fields
+ *
+ * A #GRelation is a table of data which can be indexed on any number
+ * of fields, rather like simple database tables. A #GRelation contains
+ * a number of records, called tuples. Each record contains a number of
+ * fields. Records are not ordered, so it is not possible to find the
+ * record at a particular index.
+ *
+ * Note that #GRelation tables are currently limited to 2 fields.
+ *
+ * To create a GRelation, use g_relation_new().
+ *
+ * To specify which fields should be indexed, use g_relation_index().
+ * Note that this must be called before any tuples are added to the
+ * #GRelation.
+ *
+ * To add records to a #GRelation use g_relation_insert().
+ *
+ * To determine if a given record appears in a #GRelation, use
+ * g_relation_exists(). Note that fields are compared directly, so
+ * pointers must point to the exact same position (i.e. different
+ * copies of the same string will not match.)
+ *
+ * To count the number of records which have a particular value in a
+ * given field, use g_relation_count().
+ *
+ * To get all the records which have a particular value in a given
+ * field, use g_relation_select(). To access fields of the resulting
+ * records, use g_tuples_index(). To free the resulting records use
+ * g_tuples_destroy().
+ *
+ * To delete all records which have a particular value in a given
+ * field, use g_relation_delete().
+ *
+ * To destroy the #GRelation, use g_relation_destroy().
+ *
+ * To help debug #GRelation objects, use g_relation_print().
+ **/
 
 typedef struct _GRealTuples        GRealTuples;
 
+/**
+ * GRelation:
+ *
+ * The #GRelation struct is an opaque data structure to represent a
+ * <link linkend="glib-Relations-and-Tuples">Relation</link>. It should
+ * only be accessed via the following functions.
+ **/
 struct _GRelation
 {
   gint fields;
@@ -49,6 +98,15 @@ struct _GRelation
   gint count;
 };
 
+/**
+ * GTuples:
+ * @len: the number of records that matched.
+ *
+ * The #GTuples struct is used to return records (or tuples) from the
+ * #GRelation by g_relation_select(). It only contains one public
+ * member - the number of records that matched. To access the matched
+ * records, you must use g_tuples_index().
+ **/
 struct _GRealTuples
 {
   gint      len;
@@ -112,6 +170,14 @@ tuple_equal (gint fields)
   return NULL;
 }
 
+/**
+ * g_relation_new:
+ * @fields: the number of fields.
+ * @Returns: a new #GRelation.
+ *
+ * Creates a new #GRelation with the given number of fields. Note that
+ * currently the number of fields must be 2.
+ **/
 GRelation*
 g_relation_new (gint fields)
 {
@@ -140,6 +206,14 @@ g_relation_free_array (gpointer key, gpointer value, gpointer user_data)
   g_hash_table_destroy ((GHashTable*) value);
 }
 
+/**
+ * g_relation_destroy:
+ * @relation: a #GRelation.
+ *
+ * Destroys the #GRelation, freeing all memory allocated. However, it
+ * does not free memory allocated for the tuple data, so you should
+ * free that first if appropriate.
+ **/
 void
 g_relation_destroy (GRelation *relation)
 {
@@ -164,6 +238,16 @@ g_relation_destroy (GRelation *relation)
     }
 }
 
+/**
+ * g_relation_index:
+ * @relation: a #GRelation.
+ * @field: the field to index, counting from 0.
+ * @hash_func: a function to produce a hash value from the field data.
+ * @key_equal_func: a function to compare two values of the given field.
+ *
+ * Creates an index on the given field. Note that this must be called
+ * before any records are added to the #GRelation.
+ **/
 void
 g_relation_index (GRelation   *relation,
                  gint         field,
@@ -177,6 +261,15 @@ g_relation_index (GRelation   *relation,
   relation->hashed_tuple_tables[field] = g_hash_table_new (hash_func, key_equal_func);
 }
 
+/**
+ * g_relation_insert:
+ * @relation: a #GRelation.
+ * @Varargs: the fields of the record to add. These must match the
+ *           number of fields in the #GRelation, and of type #gpointer
+ *           or #gconstpointer.
+ *
+ * Inserts a record into a #GRelation.
+ **/
 void
 g_relation_insert (GRelation   *relation,
                   ...)
@@ -257,6 +350,16 @@ g_relation_delete_tuple (gpointer tuple_key,
   relation->count -= 1;
 }
 
+/**
+ * g_relation_delete:
+ * @relation: a #GRelation.
+ * @key: the value to compare with.
+ * @field: the field of each record to match.
+ * @Returns: the number of records deleted.
+ *
+ * Deletes any records from a #GRelation that have the given key value
+ * in the given field.
+ **/
 gint
 g_relation_delete  (GRelation     *relation,
                    gconstpointer  key,
@@ -309,6 +412,17 @@ g_relation_select_tuple (gpointer tuple_key,
   tuples->len += 1;
 }
 
+/**
+ * g_relation_select:
+ * @relation: a #GRelation.
+ * @key: the value to compare with.
+ * @field: the field of each record to match.
+ * @Returns: the records (tuples) that matched.
+ *
+ * Returns all of the tuples which have the given key in the given
+ * field. Use g_tuples_index() to access the returned records. The
+ * returned records should be freed with g_tuples_destroy().
+ **/
 GTuples*
 g_relation_select (GRelation     *relation,
                   gconstpointer  key,
@@ -343,6 +457,16 @@ g_relation_select (GRelation     *relation,
   return (GTuples*)tuples;
 }
 
+/**
+ * g_relation_count:
+ * @relation: a #GRelation.
+ * @key: the value to compare with.
+ * @field: the field of each record to match.
+ * @Returns: the number of matches.
+ *
+ * Returns the number of tuples in a #GRelation that have the given
+ * value in the given field.
+ **/
 gint
 g_relation_count (GRelation     *relation,
                  gconstpointer  key,
@@ -365,6 +489,17 @@ g_relation_count (GRelation     *relation,
   return g_hash_table_size (key_table);
 }
 
+/**
+ * g_relation_exists:
+ * @relation: a #GRelation.
+ * @Varargs: the fields of the record to compare. The number must match
+ *           the number of fields in the #GRelation.
+ * @Returns: %TRUE if a record matches.
+ *
+ * Returns %TRUE if a record with the given values exists in a
+ * #GRelation. Note that the values are compared directly, so that, for
+ * example, two copies of the same string will not match.
+ **/
 gboolean
 g_relation_exists (GRelation   *relation, ...)
 {
@@ -387,6 +522,15 @@ g_relation_exists (GRelation   *relation, ...)
   return result;
 }
 
+/**
+ * g_tuples_destroy:
+ * @tuples: the tuple data to free.
+ *
+ * Frees the records which were returned by g_relation_select(). This
+ * should always be called after g_relation_select() when you are
+ * finished with the records. The records are not removed from the
+ * #GRelation.
+ **/
 void
 g_tuples_destroy (GTuples *tuples0)
 {
@@ -399,6 +543,17 @@ g_tuples_destroy (GTuples *tuples0)
     }
 }
 
+/**
+ * g_tuples_index:
+ * @tuples: the tuple data, returned by g_relation_select().
+ * @index_: the index of the record.
+ * @field: the field to return.
+ * @Returns: the field of the record.
+ *
+ * Gets a field from the records returned by g_relation_select(). It
+ * returns the given field of the record at the given index. The
+ * returned value should not be changed.
+ **/
 gpointer
 g_tuples_index (GTuples     *tuples0,
                gint         index,
@@ -455,6 +610,13 @@ g_relation_print_index (gpointer tuple_key,
                        rel);
 }
 
+/**
+ * g_relation_print:
+ * @relation: a #GRelation.
+ *
+ * Outputs information about all records in a #GRelation, as well as
+ * the indexes. It is for debugging.
+ **/
 void
 g_relation_print (GRelation *relation)
 {