Add gtkdoc to various functions

ChangeLog

@@ -1,3 +1,9 @@
+Mon Jun 21 23:18:18 CDT 2004	Jeff Smith <whydoubt@yahoo.com>
+	* src/libmdb/backend.c:
+	* src/libmdb/file.c:
+	* src/libmdb/like.c:
+	* src/libmdb/money.c: Add gtkdoc to various functions
+
 Sun Jun 20 09:37:58 EDT 2004	Brian Bruns <brian@bruns.com.
 	* configure.in: 
 	* acinclude.m4: use READLINE macro from Ville Laurikari. Remove full macroset to work around broken BSD autoconf.  Add macro for iconv detection.

src/libmdb/backend.c

@@ -134,6 +134,7 @@ static MdbBackendType mdb_mysql_types[] = {
 		{"numeric",1,1,0},
 };
 
+static gboolean mdb_drop_backend(gpointer key, gpointer value, gpointer data);
 
 char *mdb_get_coltype_string(MdbBackend *backend, int col_type)
 {
@@ -153,10 +154,12 @@ int mdb_coltype_takes_length(MdbBackend *backend, int col_type)
 	return backend->types_table[col_type].needs_length;
 }
 
-/*
-** mdb_init_backends() initializes the mdb_backends hash and loads the builtin
-** backends
-*/
+/**
+ * mdb_init_backends
+ *
+ * Initializes the mdb_backends hash and loads the builtin backends.
+ * Use mdb_remove_backends() to destroy this hash when done.
+ */
 void mdb_init_backends()
 {
 	MdbBackend *backend;
@@ -176,17 +179,32 @@ void mdb_register_backend(MdbBackendType *backend_type, char *backend_name)
 	g_hash_table_insert(mdb_backends, backend_name, backend);
 }
 
+/**
+ * mdb_remove_backends
+ *
+ * Removes all entries from and destroys the mdb_backends hash.
+ */
+void mdb_remove_backends()
+{
+	g_hash_table_foreach_remove(mdb_backends, mdb_drop_backend, NULL);
+	g_hash_table_destroy(mdb_backends);
+}
 static gboolean mdb_drop_backend(gpointer key, gpointer value, gpointer data)
 {
 	MdbBackend *backend = (MdbBackend *)value;
 	g_free (backend);
 	return TRUE;
 }
-void mdb_remove_backends()
-{
-	g_hash_table_foreach_remove(mdb_backends, mdb_drop_backend, NULL);
-	g_hash_table_destroy(mdb_backends);
-}
+
+/**
+ * mdb_set_default_backend
+ * @mdb: Handle to open MDB database file
+ * @backend_name: Name of the backend to set as default
+ *
+ * Sets the default backend of the handle @mdb to @backend_name.
+ *
+ * Returns: 1 if successful, 0 if unsuccessful.
+ */
 int mdb_set_default_backend(MdbHandle *mdb, char *backend_name)
 {
 	MdbBackend *backend;
@@ -202,12 +220,20 @@ int mdb_set_default_backend(MdbHandle *mdb, char *backend_name)
 	}
 }
 
-/*
- * generate relationships by reading the MSysRelationships table
- *   szColumn contains the column name of the child table
- *   szObject contains the table name of the child table
- *   szReferencedColumn contains the column name of the parent table
- *   szReferencedObject contains the table name of the parent table
+/**
+ * mdb_get_relationships
+ * @mdb: Handle to open MDB database file
+ *
+ * Generates relationships by reading the MSysRelationships table.
+ *   'szColumn' contains the column name of the child table.
+ *   'szObject' contains the table name of the child table.
+ *   'szReferencedColumn' contains the column name of the parent table.
+ *   'szReferencedObject' contains the table name of the parent table.
+ *
+ * Returns: a string stating that relationships are not supported for the
+ *   selected backend, or a string containing SQL commands for setting up
+ *   the relationship, tailored for the selected backend.  The caller is
+ *   responsible for freeing this string.
  */
 char *mdb_get_relationships(MdbHandle *mdb)
 {

src/libmdb/file.c

@@ -58,7 +58,7 @@ static size_t _mdb_read_pg(MdbHandle *mdb, unsigned char *pg_buf, unsigned long
  * mdb_find_file:
  * @filename: path to MDB (database) file
  *
- * Finds and returns the absolute path to an MDB file.  Function will first try                                                                                
+ * Finds and returns the absolute path to an MDB file.  Function will first try
  * to fstat file as passed, then search through the $MDBPATH if not found.
  *
  * Return value: gchar pointer to absolute path. Caller is responsible for

src/libmdb/like.c

@@ -25,6 +25,17 @@
 #include "dmalloc.h"
 #endif
 
+/**
+ * mdb_like_cmp
+ * @s: String to search within.
+ * @r: Search pattern.
+ *
+ * Tests the string @s to see if it matches the search pattern @r.  In the
+ * search pattern, a percent sign indicates matching on any number of
+ * characters, and an underscore indicates matching any single character.
+ *
+ * Returns: 1 if the string matches, 0 if the string does not match.
+ */
 int mdb_like_cmp(char *s, char *r)
 {
 int i, ret;

src/libmdb/money.c

@@ -34,6 +34,14 @@ static int multiply_byte(unsigned char *product, int num, unsigned char *multipl
 static int do_carry(unsigned char *product);
 static char *array_to_string(unsigned char *array, int scale, char *s);
 
+/**
+ * mdb_money_to_string
+ * @mdb: Handle to open MDB database file
+ * @start: Offset of the field within the current page
+ * @s: String that will receieve the value
+ *
+ * Returns: the string that has received the value.
+ */
 char *mdb_money_to_string(MdbHandle *mdb, int start, char *s)
 {
 unsigned char multiplier[MAXPRECISION], temp[MAXPRECISION];