From ff84e9e985f187ebcc7bbb365027831fe3f970ad Mon Sep 17 00:00:00 2001
From: Adam Dickmeiss <adam@indexdata.dk>
Date: Sun, 1 May 2005 20:43:11 +0000
Subject: [PATCH] Doxygen stuff: added more about each module.

---
 include/idzebra/api.h  |   74 ++++++++++++++++++++++++++++++++++++++++++------
 include/idzebra/dict.h |   15 +++++++++-
 2 files changed, 80 insertions(+), 9 deletions(-)

diff --git a/include/idzebra/api.h b/include/idzebra/api.h
index 953c927..cffa896 100644
--- a/include/idzebra/api.h
+++ b/include/idzebra/api.h
@@ -1,4 +1,4 @@
-/* $Id: api.h,v 1.20 2005-04-29 23:09:57 adam Exp $
+/* $Id: api.h,v 1.21 2005-05-01 20:43:11 adam Exp $
    Copyright (C) 1995-2005
    Index Data ApS
 
@@ -469,19 +469,77 @@ YAZ_END_CDECL
  *
  * \section intro_sec Introduction
  *
- * Zebra is a search engine for structure data. It includes the
- * following components: util, dict, isam, recctrl, filters.
+ * Zebra is a search engine for structure data, such as XML, MARC
+ * and others. The following chapters briefly describe each of
+ * Zebra major modules/components.
  *
- * \section util util
+ * \section util Base Utilities
  *
- * \section dict dict
+ * The Zebra utilities (util.h) defines fundamental types and a few
+ * utilites for Zebra.
  *
- * \section isam isam
+ * \section res Resources
  *
- * \section data1 data-1
+ * The resources system (res.h) is a manager of configuration 
+ * resources. The resources can be viewed as a simple database.
+ * Resources can be read from a configurtion file, they can be
+ * read or written by an application. Resources can also be written,
+ * but that facility is not currently in use.
  *
- * \section recctrl recctrl
+ * \section bfile Bfiles
  *
+ * The Bfiles (bfile.h) provides a portable interface to the
+ * local file system. It also provides a facility for safe updates
+ * (shadow updates). All file system access is handle by this module
+ * (except for trival reads of configuration files).
+ *
+ * \section dict Dictionary
+ *
+ * The Zebra dictionary (dict.h) maps a search term (key) to a value. The
+ * value is a reference to the list of records identifers in which
+ * the term occurs. Zebra uses an ISAM data structure for the list
+ * of term occurrences. The Dictionary uses \ref bfile.
+ *
+ * \section isam ISAM
+ *
+ * Zebra maintains an ISAM for each term where each ISAM is a list
+ * of record identifiers corresponding to the records in which the
+ * term occur. Unlike traditional ISAM systems, the Zebra ISAM
+ * is compressed. The ISAM system uses \ref bfile.
+ *
+ * Zebra has more than one ISAM system. The old and stable ISAM system
+ * is named isamc (see isamc.h). Another version isams is a write-once
+ * isam system that is quite compact - suitable for CD-ROMs (isams.h). 
+ * The newest ISAM system, isamb, is implemented as a B-Tree (see isamb.h).
+ *
+ * \section data1 Data-1
+ *
+ * The data1 (data1.h) module deals with structured documents. The module can
+ * can read, modify and write documents. The document structure was
+ * originally based on GRS-1 - a Z39.50 v3 structure that predates
+ * DOM. These days the data1 structure may describe XML/SGML as well.
+ * The data1, like DOM, is a tree structure. Each node in the tree
+ * can be of type element, text (cdata), preprocessing instruction,
+ * comment. Element nodes can point to attribute nodes.
+ *
+ * \section recctrl Record Control
+ *
+ * The record control module (recctrl.h) is responsible for
+ * managing the various record types ("classes" or filters).
+ *
+ * \section rset Result-Set
+ *
+ * The Result-Set module (rset.h) defines an interface that all
+ * Zebra Search Results must implement. Each operation (AND, OR, ..)
+ * correspond to an implementation of that interface.
+ *
+ * \section dfa DFA
+ *
+ * DFA (dfa.h) Deterministic Finite Automa is a regular expression engine.
+ * The module compiles a regular expression to a DFA. The DFA can then
+ * be used in various application to perform fast match against the
+ * origianl expression. The \ref Dict uses DFA to perform lookup
+ * using regular expressions.
  */
 
 #endif
diff --git a/include/idzebra/dict.h b/include/idzebra/dict.h
index b8612dc..a620165 100644
--- a/include/idzebra/dict.h
+++ b/include/idzebra/dict.h
@@ -1,4 +1,4 @@
-/* $Id: dict.h,v 1.3 2005-01-15 19:38:24 adam Exp $
+/* $Id: dict.h,v 1.4 2005-05-01 20:43:11 adam Exp $
    Copyright (C) 1995-2005
    Index Data ApS
 
@@ -20,6 +20,14 @@ Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 02111-1307, USA.
 */
 
+/** \file dict.h
+    \brief Zebra dictionary
+    
+    The dictionary is a hash that maps a string to a value.
+    The value is opaque and is defined as a sequence of bytes
+    with a length in the range 0 to 255.
+*/
+
 #ifndef DICT_H
 #define DICT_H
 
@@ -28,6 +36,11 @@ Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 
 YAZ_BEGIN_CDECL
 
+/** \var Dict
+ * \brief Dictionary type
+ *
+ * Most dictionary functions operatate on a Dict type (object).
+ */
 typedef struct Dict_struct *Dict;
 
 typedef unsigned Dict_ptr;
-- 
1.7.10.4