add gtk-doc-style comments

svn path=/trunk/; revision=1936

5 files changed, 144 insertions, 8 deletions

diff --git a/libibex/ChangeLog b/libibex/ChangeLog
index a4a15182e2..ba785db21a 100644
--- a/libibex/ChangeLog
+++ b/libibex/ChangeLog
@@ -1,11 +1,16 @@
+2000-02-25  Dan Winship  <danw@helixcode.com>
+
+	* *.c: add gtk-doc-style comments
+
 2000-02-21  Matt Loper  <matt@helixcode.com>
 
 	* .cvsignore: Added mkindex.
 
 2000-02-21  NotZed  <NotZed@HelixCode.com>
 
-	* Makefile.am: change noinst_LIBRARIES to noinst_LTLIBRARIES, and supply -static to
-	LDFLAGS.  Duh, and changed LDADD back to libibex.la.
+	* Makefile.am: change noinst_LIBRARIES to noinst_LTLIBRARIES, and
+	supply -static to LDFLAGS.  Duh, and changed LDADD back to
+	libibex.la.
 
 2000-02-20  Matt Loper  <matt@helixcode.com>
 
diff --git a/libibex/file.c b/libibex/file.c
index 57b31af89f..0cf637764e 100644
--- a/libibex/file.c
+++ b/libibex/file.c
@@ -52,6 +52,16 @@ static void free_word (gpointer key, gpointer value, gpointer data);
  * line has in common with the line before it, followed by the rest of
  * the string. Obviously this only really works if the lists are sorted.
  */
+
+/**
+ * ibex_open: open (or possibly create) an ibex index
+ * @file: the name of the file
+ * @create: whether or not to create the file if it doesn't exist.
+ *
+ * Open and/or create the named ibex file and return a handle to it.
+ *
+ * Return value: an ibex handle, or NULL if an error occurred.
+ **/
 ibex *
 ibex_open (char *file, gboolean create)
 {
@@ -151,6 +161,9 @@ struct ibex_write_data {
 	char *lastname;
 };
 
+/* This is an internal function to find the longest common initial
+ * prefix between the last-written word and the current word.
+ */
 static int
 get_prefix (struct ibex_write_data *iwd, char *name)
 {
@@ -219,6 +232,15 @@ write_word (gpointer key, gpointer value, gpointer data)
 	return FALSE;
 }
 
+/**
+ * ibex_write: Write an ibex out to disk.
+ * @ib: the ibex
+ *
+ * This writes an ibex to disk.
+ *
+ * Return value: 0 for success, -1 for failure (in which case errno
+ * is set).
+ **/
 int
 ibex_write (ibex *ib)
 {
@@ -271,6 +293,19 @@ lose:
 	return -1;
 }
 
+/**
+ * ibex_close: Write out the ibex file (if it has changed) and free
+ * the data associated with it.
+ * @ib: the ibex
+ *
+ * If this ibex file has been modified since it was opened, this will
+ * call ibex_write() to write it out to disk. It will then free all data
+ * associated with the ibex. After calling ibex_close(), @ib will no
+ * longer be a valid ibex.
+ *
+ * Return value: 0 on success, -1 on an ibex_write() failure (in which
+ * case @ib will not be destroyed).
+ **/
 int
 ibex_close (ibex *ib)
 {
diff --git a/libibex/find.c b/libibex/find.c
index f449144e61..91e611401c 100644
--- a/libibex/find.c
+++ b/libibex/find.c
@@ -24,6 +24,19 @@
 
 #include "ibex_internal.h"
 
+/**
+ * ibex_find: search an ibex for a word
+ * @ib: an ibex
+ * @word: the word
+ *
+ * This routine searches an ibex for a word and returns a GPtrArray
+ * containing the names of the files in the ibex that contain the word.
+ * If no matches are found, it will return an empty array (not NULL).
+ * The caller must free the array, but MUST NOT free or alter its
+ * elements.
+ *
+ * Return value: the array of filenames containing @word
+ **/
 GPtrArray *
 ibex_find (ibex *ib, char *word)
 {
@@ -42,6 +55,16 @@ ibex_find (ibex *ib, char *word)
 	return ret;
 }
 
+/**
+ * ibex_find_name: Check if a word occurs in a given file
+ * @ib: an ibex
+ * @name: a filename
+ * @word: a word
+ *
+ * This checks if the given word occurs in the given file.
+ *
+ * Return value: TRUE or FALSE
+ **/
 gboolean
 ibex_find_name (ibex *ib, char *name, char *word)
 {
@@ -72,6 +95,16 @@ build_array (gpointer key, gpointer value, gpointer data)
 	return FALSE;
 }
 
+/**
+ * ibex_find_all: Find files containing multiple words
+ * @ib: an ibex
+ * @words: a GPtrArray of words
+ *
+ * This works like ibex_find(), but returns an array of filenames
+ * which contain all of the words in @words.
+ *
+ * Return value: an array of matches
+ **/
 GPtrArray *
 ibex_find_all (ibex *ib, GPtrArray *words)
 {
diff --git a/libibex/index.c b/libibex/index.c
index 895cbf50be..5e3e9cf588 100644
--- a/libibex/index.c
+++ b/libibex/index.c
@@ -28,9 +28,17 @@
 
 #include "ibex_internal.h"
 
-/* Index a file, given its name. (Replace any previously indexed contents
- * of this file with the new contents.)
- */
+/**
+ * ibex_index_file: Index a file by name
+ * @ib: an ibex
+ * @filename: name of the file to index
+ *
+ * This indexes the given file into @ib. If @filename is already in
+ * the ibex, the existing index entries for it are discarded and the
+ * file is indexed anew.
+ *
+ * Return value: 0 on success, -1 on failure.
+ **/
 int
 ibex_index_file (ibex *ib, char *filename)
 {
@@ -58,9 +66,27 @@ ibex_index_file (ibex *ib, char *filename)
 	return status;
 }
 
-/* Given a file descriptor and a name to refer to it by, index LEN
- * bytes of data from it.
- */
+/**
+ * ibex_index_fd: Index a file given a file descriptor
+ * @ib: an ibex
+ * @name: the name of the file being indexed
+ * @fd: a file descriptor, open for reading
+ * @len: the number of bytes to read from the file
+ *
+ * This indexes a file, or a part of a file, given an open file
+ * descriptor and a size. There is no requirement that @name
+ * actually correspond to @fd in any particular way.
+ *
+ * If the function returns successfully, the file descriptor offset of
+ * @fd will be exactly @len bytes beyond where it was when the
+ * function was called. The indexer assumes that this point is a word
+ * boundary.
+ *
+ * The behavior of this function is not defined if it is not
+ * possible to read @len bytes off @fd.
+ *
+ * Return value: 0 on success, -1 on failure.
+ **/
 int
 ibex_index_fd (ibex *ib, char *name, int fd, size_t len)
 {
@@ -83,6 +109,14 @@ ibex_index_fd (ibex *ib, char *name, int fd, size_t len)
 	return status;
 }
 
+/**
+ * ibex_unindex: Remove a file from the ibex
+ * @ib: an ibex
+ * @name: name of the file to remove
+ *
+ * This removes all references to @name from @ib. No memory is freed
+ * right away, but further searches on @ib will never return @name.
+ **/
 void
 ibex_unindex (ibex *ib, char *name)
 {
@@ -96,6 +130,14 @@ ibex_unindex (ibex *ib, char *name)
 	}
 }
 
+/**
+ * ibex_rename: Rename a file in the ibex
+ * @ib: an ibex
+ * @oldname: the old name of the file
+ * @newname: the new name of the file
+ *
+ * This renames a file in the ibex.
+ **/
 void
 ibex_rename (ibex *ib, char *oldname, char *newname)
 {
diff --git a/libibex/words.c b/libibex/words.c
index 1a5a4d5680..40e0452403 100644
--- a/libibex/words.c
+++ b/libibex/words.c
@@ -184,6 +184,27 @@ ref_word (ibex *ib, ibex_file *ibf, char *word)
 	}
 }
 
+/**
+ * ibex_index_buffer: the lowest-level ibex indexing interface
+ * @ib: an ibex
+ * @name: the name of the file being indexed
+ * @buffer: a buffer containing data from the file
+ * @len: the length of @buffer
+ * @unread: an output argument containing the number of unread bytes
+ *
+ * This routine indexes up to @len bytes from @buffer into @ib.
+ * If @unread is NULL, the indexer assumes that the buffer ends on a
+ * word boundary, and will index all the way to the end of the
+ * buffer. If @unread is not NULL, and the buffer ends with an
+ * alphabetic character, the indexer will assume that the buffer has
+ * been cut off in the middle of a word, and return the number of
+ * un-indexed bytes at the end of the buffer in *@unread. The caller
+ * should then read in more data through whatever means it has
+ * and pass in the unread bytes from the original buffer, followed
+ * by the new data, on its next call.
+ *
+ * Return value: 0 on success, -1 on failure.
+ **/
 int
 ibex_index_buffer (ibex *ib, char *name, char *buffer,
 		   size_t len, size_t *unread)