update documentation structure so that doxygen generates nice output

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@9939 57a11ea4-9604-0410-9ed3-97b8803252fd

src/engine/gnc-date.h

@@ -17,19 +17,9 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
 \********************************************************************/
 /** @addtogroup Date
-    @{ */
-/** @file gnc-date.h 
-    @brief Date and Time handling routines  
-    *
     Utility functions to handle date and time (adjusting, getting 
     the current date, printing the date and time, etc.) 
 
-    \warning HACK ALERT -- the scan and print routines should probably be moved
-    to somewhere else. The engine really isn't involved with things
-    like printing formats. This is needed mostly by the GUI and so on.
-    If a file-io backend needs date handling, it should do it itself,
-    instead of depending on the routines here. 
-
     Overall, this file is quite a mess.  Note, however, that other 
     applications, besides just GnuCash, use this file.  In particular,
     GnoTime (gttr.sourcefore.net) uses this file, and this file is 
@@ -50,10 +40,21 @@
     that is not Universal Time.  Break these rules, and you will 
     rue the day...
 
+    \warning HACK ALERT -- the scan and print routines should probably be moved
+    to somewhere else. The engine really isn't involved with things
+    like printing formats. This is needed mostly by the GUI and so on.
+    If a file-io backend needs date handling, it should do it itself,
+    instead of depending on the routines here. 
+
     @author Copyright (C) 1997 Robin D. Clark <rclark@cs.hmc.edu> 
     @author Copyright (C) 1998-2001,2003 Linas Vepstas <linas@linas.org>
 */
 
+/* @{ 
+    @file gnc-date.h 
+    @brief Date and Time handling routines  
+*/
+    
 #ifndef GNC_DATE_H
 #define GNC_DATE_H
 

src/engine/gnc-engine-util.h

@@ -19,7 +19,7 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
 \********************************************************************/
 
-/** @addtogroup Engine
+/** @addtogroup Utilities
     @{ */
 /** @file gnc-engine-util.h 
     @brief GnuCash engine utility functions 
@@ -130,7 +130,7 @@ int qof_util_bool_to_int (const char * val);
  * cached the strings are just plain C strings.
  */
 
-/* get the gnc_string_cache.  Create it if it doesn't exist already */
+/** Get the gnc_string_cache.  Create it if it doesn't exist already */
 GCache* gnc_engine_get_string_cache(void);
 
 void gnc_engine_string_cache_destroy (void);

src/engine/gnc-numeric.h

@@ -1,4 +1,5 @@
 /********************************************************************
+ * gnc-numeric.h - An exact-number library for gnucash              *
  * This program is free software; you can redistribute it and/or    *
  * modify it under the terms of the GNU General Public License as   *
  * published by the Free Software Foundation; either version 2 of   *
@@ -19,6 +20,19 @@
  *******************************************************************/
 
 /** @addtogroup Numeric
+    The 'Numeric' functions provide a way of working with rational
+    numbers while maintaining strict control over rounding errors
+    when adding rationals with different denominators.  The Numeric
+    class is primarily used for working with monetary amounts, 
+    where the denominator typically represents the smallest fraction
+    of the currency (e.g. pennies, centimes).  The numeric class
+    can handle any fraction (e.g. twelfth's) and is not limited
+    to fractions that are powers of ten.
+
+    Please refer to the GnuCash texinfo documentation for details 
+    on the numeric functions.  (The texinfo will someday be
+    brought inline, here, into this file).
+
     @{ */
 /** @file gnc-numeric.h
     @brief An exact-rational-number library for gnucash.
@@ -35,7 +49,7 @@ struct _gnc_numeric {
   gint64  denom;
 };
 
-/** @brief An exact-number type for gnucash. 
+/** @brief An exact-number type
  *
  * This is a rational number, defined by nominator and denominator. */
 typedef struct _gnc_numeric gnc_numeric;

src/engine/gnc-trace.h

@@ -22,7 +22,7 @@
  *   Author: Linas Vepstas (linas@linas.org)                        *
 \********************************************************************/
 
-/** @addtogroup Engine
+/** @addtogroup Trace
     @{ */
 
 /** @file gnc-trace.h 
@@ -133,11 +133,13 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
  * handle.
  */
 
+/** Log an fatal error */
 #define FATAL(format, args...) {                     \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_ERROR,          \
       "Fatal Error: %s(): " format, FUNK , ## args); \
 }
 
+/** Log an serious error */
 #define PERR(format, args...) {                    \
   if (gnc_should_log (module, GNC_LOG_ERROR)) {    \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL,     \
@@ -145,6 +147,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
   }                                                \
 }
 
+/** Log an warning */
 #define PWARN(format, args...) {                   \
   if (gnc_should_log (module, GNC_LOG_WARNING)) {  \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING,      \
@@ -152,6 +155,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
   }                                                \
 }
 
+/** Print an informational note */
 #define PINFO(format, args...) {                   \
   if (gnc_should_log (module, GNC_LOG_INFO)) {     \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_INFO,         \
@@ -159,6 +163,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
   }                                                \
 }
 
+/** Print an debugging message */
 #define DEBUG(format, args...) {                   \
   if (gnc_should_log (module, GNC_LOG_DEBUG)) {    \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,        \
@@ -166,6 +171,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
   }                                                \
 }
 
+/** Print an function entry debugging message */
 #define ENTER(format, args...) {                   \
   if (gnc_should_log (module, GNC_LOG_DEBUG)) {    \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,        \
@@ -173,6 +179,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
   }                                                \
 }
 
+/** Print an function exit debugging message */
 #define LEAVE(format, args...) {                   \
   if (gnc_should_log (module, GNC_LOG_DEBUG)) {    \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,        \
@@ -180,6 +187,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
   }                                                \
 }
 
+/** Print an function trace debugging message */
 #define TRACE(format, args...) {                   \
   if (gnc_should_log (module, GNC_LOG_TRACE)) {    \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,        \
@@ -190,7 +198,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
 #define DEBUGCMD(x) { if (gnc_should_log (module, GNC_LOG_DEBUG)) { (x); }}
 
 /* -------------------------------------------------------- */
-/* Infrastructure to make timing measurements for critical peices 
+/** Infrastructure to make timing measurements for critical peices 
  * of code. Used for only for performance tuning & debugging. 
  */
 
@@ -209,18 +217,21 @@ void gnc_report_clock_total (int clockno,
                              const char *function_name,
                              const char *format, ...);
 
+/** start a particular timer */
 #define START_CLOCK(clockno,format, args...) {              \
   if (gnc_should_log (module, GNC_LOG_INFO))                \
     gnc_start_clock (clockno, module, GNC_LOG_INFO,         \
              __FUNCTION__, format , ## args);               \
 }
 
+/** report elapsed time since last report on a particular timer */
 #define REPORT_CLOCK(clockno,format, args...) {             \
   if (gnc_should_log (module, GNC_LOG_INFO))                \
     gnc_report_clock (clockno, module, GNC_LOG_INFO,        \
              __FUNCTION__, format , ## args);               \
 }
 
+/** report total elapsed time since timer started */
 #define REPORT_CLOCK_TOTAL(clockno,format, args...) {       \
   if (gnc_should_log (module, GNC_LOG_INFO))                \
     gnc_report_clock_total (clockno, module, GNC_LOG_INFO,  \

src/engine/guid.h

@@ -27,7 +27,20 @@
 #include <glib.h>
 #include <stddef.h>
 
+/** @addtogroup Entity
+    @{ */
 /** @addtogroup GUID
+    Globally Unique ID's provide a way to uniquely identify 
+    some thing.  A GUID is a unique, cryptographically
+    random 128-bit value.  The identifier is so random that
+    it is safe to assume that there is no other such item
+    on the planet Earth, and indeed, not even in the Galaxy
+    or beyond.
+
+    QOF GUID's can be used independently of any other subsystem
+    in QOF.   In particular, they do not require the use of
+    other parts of the object subsystem.
+
     @{ */
 /** @file guid.h
     @brief  globally unique ID User API 
@@ -44,7 +57,7 @@ typedef union _GUID
 } GUID;
 
 
-/* number of characters needed to encode a guid as a string
+/** number of characters needed to encode a guid as a string
  * not including the null terminator. */
 #define GUID_ENCODING_LENGTH 32
 
@@ -180,5 +193,6 @@ guint guid_hash_to_guint(gconstpointer ptr);
 
 GHashTable *guid_hash_table_new(void);
 
+/* @} */
 /* @} */
 #endif

src/engine/kvp-util-p.h

@@ -28,7 +28,10 @@
 #include "guid.h"
 #include "kvp_frame.h"
 
-/** @addtogroup KVP_Util
+/** @addtogroup KVP
+    @{ */
+/** @addtogroup KVP_Private
+    Private interfaces, not meant to be used by applications.
     @{ */
 /* @file kvp-util-p.h
  * @brief misc odd-job kvp utils engine-private routines
@@ -37,6 +40,8 @@
  * -- these routines are private to the engine. The should not be used 
  *    outside of the engine.
  */
+/** @name KvpBag Bags of GUID Pointers */
+/* @{ */
 
 /** The gnc_kvp_bag_add() routine is used to maintain a collection 
  *  of pointers in a kvp tree.
@@ -102,5 +107,7 @@ KvpFrame * gnc_kvp_bag_find_by_guid (KvpFrame *root,  const char * path,
 void gnc_kvp_bag_remove_frame (KvpFrame *root, const char *path,
                                KvpFrame *fr);
 
+/* @} */
+/* @} */
 /* @} */
 #endif /* XACC_KVP_UTIL_P_H */

src/engine/kvp-util.h

@@ -20,19 +20,26 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
 \********************************************************************/
 
-/** @addtogroup KVP_Util
+/** @addtogroup KVP
     @{ */
 /** @file kvp-util.h 
-    @brief GnuCash KVP utility functions */
+    @brief GnuCash KVP utility functions 
+ */
+/**  @name Hash Utilities */
+/* @{ */
 
 #ifndef GNC_KVP_UTIL_H
 #define GNC_KVP_UTIL_H
 
 #include "config.h"
 
-/***********************************************************************\
+typedef struct {
+  gpointer key;
+  gpointer value;
+} GHashTableKVPair;
 
-  g_hash_table_key_value_pairs(hash): Returns a GSList* of all the
+/** 
+  Returns a GSList* of all the
   keys and values in a given hash table.  Data elements of lists are
   actual hash elements, so be careful, and deallocation of the
   GHashTableKVPairs in the result list are the caller's
@@ -45,15 +52,11 @@
 
 */
 
-typedef struct {
-  gpointer key;
-  gpointer value;
-} GHashTableKVPair;
-
 GSList *g_hash_table_key_value_pairs(GHashTable *table);
 void g_hash_table_kv_pair_free_gfunc(gpointer data, gpointer user_data);
 
 /***********************************************************************/
 
+/* @} */
 /* @} */
 #endif /* GNC_KVP_UTIL_H */

src/engine/kvp_frame.h

@@ -19,23 +19,8 @@
  *                                                                  *
 \********************************************************************/
 /** @addtogroup KVP
-    @{ */
-/** @file kvp_frame.h
-    @brief A key-value frame system
-    @author Copyright (C) 2000 Bill Gribble
-    @author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
-*/
 
-#ifndef KVP_FRAME_H
+ * A KvpFrame is a set of associations between character strings
-#define KVP_FRAME_H
-
-#include <glib.h>
-
-#include "gnc-date.h"
-#include "gnc-numeric.h"
-#include "guid.h"
-
-/** a KvpFrame is a set of associations between character strings
  * (keys) and KvpValue structures.  A KvpValue is a union with
  * possible types enumerated in the KvpValueType enum, and includes, 
  * among other things, ints, doubles, strings, guid's, lists, time
@@ -61,10 +46,27 @@
  * a key such as 'some/key' or 'some/./other/../key' because you
  * may get unexpected results.
  * 
- * In almost all cases, you want to be using the kvp_frame_set_gint64()
+ * To set a value into a frame, you will want to use one of the 
- * routine or one of its brothers.  Most of the other routines provide
+ * kvp_frame_set_xxx() routines.  Most of the other routines provide
- * only low-level access.
+ * only low-level access that you probably shouldn't use.
- */
+ 
+@{ */
+/** @file kvp_frame.h
+    @brief A key-value frame system
+    @author Copyright (C) 2000 Bill Gribble
+    @author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
+*/
+
+#ifndef KVP_FRAME_H
+#define KVP_FRAME_H
+
+#include <glib.h>
+
+#include "gnc-date.h"
+#include "gnc-numeric.h"
+#include "guid.h"
+
+/** Opaque frame structure */
 typedef struct _KvpFrame KvpFrame;
 
 /** A KvpValue is a union with possible types enumerated in the

src/engine/qofbackend-p.h

@@ -21,21 +21,20 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
+/** @addtogroup Object
+    @{ */
+/** @addtogroup Object_Private
+    Private interfaces, not meant to be used by applications.
+    @{ */
+/** @name  Backend_Private
+   Pseudo-object defining how the engine can interact with different
+   back-ends (which may be SQL databases, or network interfaces to 
+   remote GnuCash servers.  In theory, file-io should be a type of 
+   backend).
    
-/* 
+   The callbacks will be called at the appropriate times during 
- * FILE:
+   a book session to allow the backend to store the data as needed.
- * qofbackend-p.h
+@{ */
- *
- * FUNCTION:
- * Pseudo-object defining how the engine can interact with different
- * back-ends (which may be SQL databases, or network interfaces to 
- * remote GnuCash servers.  In theory, file-io should be a type of 
- * backend).
- * 
- * The callbacks will be called at the appropriate times during 
- * a book session to allow the backend to store the data as needed.
- *
- */
 
 #ifndef QOF_BACKEND_P_H
 #define QOF_BACKEND_P_H
@@ -47,7 +46,7 @@
 #include "qofquery.h"
 #include "qofsession.h"
 
-/*
+/**
  * The session_begin() routine gives the backend a second initialization
  *    opportunity.  It is suggested that the backend check that 
  *    the URL is syntactically correct, and that it is actually
@@ -255,7 +254,7 @@ struct _QofBackend
   QofBackendError last_err;
   char * error_msg;
 
-  /* XXX price_lookup should be removed during the redesign
+  /** XXX price_lookup should be removed during the redesign
    * of the SQL backend... prices can now be queried using
    * the generic query mechanism.
    *
@@ -265,32 +264,39 @@ struct _QofBackend
    */
   void (*price_lookup) (QofBackend *, gpointer);
 
-  /* XXX Export should really _NOT_ be here, but is left here for now.
+  /** XXX Export should really _NOT_ be here, but is left here for now.
    * I'm not sure where this should be going to. It should be
    * removed ASAP. 
    */
   void (*export) (QofBackend *, QofBook *);
 };
 
-/*
+/**
  * The qof_backend_set_error() routine pushes an error code onto the error
  *   stack. (FIXME: the stack is 1 deep in current implementation).
- *
+ */
+void qof_backend_set_error (QofBackend *be, QofBackendError err);
+
+/**
  * The qof_backend_get_error() routine pops an error code off the error
  *   stack.
- *
+ */
+QofBackendError qof_backend_get_error (QofBackend *be);
+/** 
  * The qof_backend_set_message() assigns a string to the backend error
  *   message.
- *
+ */
+void qof_backend_set_message(QofBackend *be, const char *format, ...);
+
+/**
  * The qof_backend_get_message() pops the error message string from
  *   the Backend.  This string should be freed with g_free().
  */
-
-void qof_backend_set_error (QofBackend *be, QofBackendError err);
-QofBackendError qof_backend_get_error (QofBackend *be);
-void qof_backend_set_message(QofBackend *be, const char *format, ...);
 char * qof_backend_get_message(QofBackend *be);
 
 void qof_backend_init(QofBackend *be);
 
+/* @} */
+/* @} */
+/* @} */
 #endif /* QOF_BACKEND_P_H */

src/engine/qofbackend.h

@@ -18,17 +18,22 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
-/** @addtogroup Backend
+/** @addtogroup Object
     @{ */
-/** @file qofbackend.h
+/** @addtogroup Backend
-    @brief api for data storage Backend
+    The QOF Backend is a pseudo-object providing an interface between the
-    *
-    The 'backend' is a pseudo-object providing an interface between the
     engine and a persistant data store (e.g. a server, a database, or
-    a file).  There are no backend functions that are 'public' to
+    a file).   Backends are not meant to be used directly by an
+    application; instead the Session should be used to make a 
+    connection with some particular backend.
+    There are no backend functions that are 'public' to
     users of the engine.  The backend can, however, report errors to
     the GUI & other front-end users.  This file defines these errors.
-    *
+   
+    Backends are used to save and restore Entities in a Book.
+    @{ */
+/** @file qofbackend.h
+    @brief API for data storage Backend
     @author Copyright (C) 2000-2001 Linas Vepstas <linas@linas.org>
 */
 
@@ -106,3 +111,4 @@ typedef void (*QofBePercentageFunc) (const char *message, double percent);
 
 #endif /* QOF_BACKEND_H */
 /**@}*/
+/**@}*/

src/engine/qofbook-p.h

@@ -19,7 +19,13 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
-
+/** @addtogroup Object
+    @{ */
+/** @addtogroup Object_Private
+    Private interfaces, not meant to be used by applications.
+    @{ */
+/** @name  Book_Private
+    @{ */
 /*
  * HISTORY:
  * Created 2001 by Rob Browning
@@ -36,50 +42,51 @@
 #include "qofid.h"
 #include "qofid-p.h"
 
+/** Book structure */
 struct _QofBook
 {
-  QofEntity   entity;     /* Unique guid for this book. */
+  QofEntity   entity;     /**< Unique guid for this book. */
 
-  /* The KvpFrame provides a place for top-level data associated 
+  /** The KvpFrame provides a place for top-level data associated 
    * with this book. */
   KvpFrame *kvp_data;
   
-  /* The entity table associates the GUIDs of all the objects
+  /** The entity table associates the GUIDs of all the objects
    * belonging to this book, with their pointers to the respective
    * objects.  This allows a lookup of objects based on thier guid.
    */
   GHashTable * hash_of_collections;
 
-  /* In order to store arbitrary data, for extensibility, add a table
+  /** In order to store arbitrary data, for extensibility, add a table
    * that will be used to hold arbitrary pointers.
    */
   GHashTable *data_tables;
 
-  /* state flag: 'y' means 'open for editing', 
+  /** state flag: 'y' means 'open for editing', 
    * 'n' means 'book is closed'  
    */
   char book_open;
 
-  /* dirty/clean flag. If dirty, then this book has been modified,
+  /** dirty/clean flag. If dirty, then this book has been modified,
    * but has not yet been written out to storage (file/database) 
    */
   gboolean dirty;
   
-  /* version number, used for tracking multiuser updates */
+  /** version number, used for tracking multiuser updates */
   gint32  version;
 
-  /* To be technically correct, backends belong to sessions and
+  /** To be technically correct, backends belong to sessions and
    * not books.  So the pointer below "really shouldn't be here", 
    * except that it provides a nice convenience, avoiding a lookup 
    * from the session.  Better solutions welcome ... */ 
   QofBackend *backend;
 
   /* -------------------------------------------------------------- */
-  /* Backend private expansion data */
+  /** Backend private expansion data */
-  guint32  idata;     /* used by the sql backend for kvp management */
+  guint32  idata;     /**< used by the sql backend for kvp management */
 };
 
-/*
+/**
  * These qof_book_set_*() routines are used by backends to 
  *    initialize the pointers in the book structure to 
  *    something that contains actual data.  These routines 
@@ -91,17 +98,20 @@ void qof_book_set_schedxactions( QofBook *book, GList *newList );
 
 void qof_book_set_backend (QofBook *book, QofBackend *be);
 
-/* The qof_book_mark_saved() routine marks the book as having been
+/** The qof_book_mark_saved() routine marks the book as having been
  *    saved (to a file, to a database). Used by backends to mark the 
  *    notsaved flag as FALSE just after loading.  Do not use otherwise!
  */
 void qof_book_mark_saved(QofBook *book);
 
-/* Register books with the engine */
+/** Register books with the engine */
 gboolean qof_book_register (void);
 
-/* deprecated */
+/** @deprecated */
 #define qof_book_set_guid(book,guid)    \
          qof_entity_set_guid(QOF_ENTITY(book), guid)
 
+/* @} */
+/* @} */
+/* @} */
 #endif /* QOF_BOOK_P_H */

src/engine/qofbook.h

@@ -1,4 +1,5 @@
 /********************************************************************\
+ * qofbook.h -- Encapsulate all the information about a dataset.    *
  * This program is free software; you can redistribute it and/or    *
  * modify it under the terms of the GNU General Public License as   *
  * published by the Free Software Foundation; either version 2 of   *
@@ -17,15 +18,21 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
+/** @addtogroup Object
+    @{ */
 /** @addtogroup Book
+    A QOF Book is a dataset.  It provides a single handle 
+    through which all the various collections of entities
+    can be found.   In particular, given only the type of
+    the entity, the collection can be found.
+    
+    Books also provide the 'natural' place to working with
+    a storage backend, as a book can encapsulate everything 
+    held in storage.
     @{ */
 /** @file qofbook.h
- * @brief dataset access (an "accounting book")
+ * @brief Encapsulate all the information about a dataset.
- * Encapsulate all the information about a dataset.
- * See src/docs/books.txt for implementation overview.
  *
- * HISTORY:
- * Created by Linas Vepstas December 1998
  * @author Copyright (c) 1998, 1999, 2001, 2003 Linas Vepstas <linas@linas.org>
  * @author Copyright (c) 2000 Dave Peticolas
  */
@@ -140,3 +147,4 @@ gint64 qof_book_get_counter (QofBook *book, const char *counter_name);
 
 #endif /* QOF_BOOK_H */
 /** @} */
+/** @} */

src/engine/qofclass-p.h

@@ -20,6 +20,13 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
+/** @addtogroup Object
+    @{ */
+/** @addtogroup Object_Private
+    Private interfaces, not meant to be used by applications.
+    @{ */
+/** @name  Class_Private
+    @{ */
 
 #ifndef QOF_CLASSP_H
 #define QOF_CLASSP_H
@@ -31,4 +38,7 @@ void qof_class_shutdown (void);
 
 QofSortFunc qof_class_get_default_sort (QofIdTypeConst obj_name);
 
+/* @} */
+/* @} */
+/* @} */
 #endif /* QOF_CLASSP_H */

src/engine/qofclass.h

@@ -20,20 +20,44 @@
  *                                                                  *
 \********************************************************************/
 
-/** @addtogroup Entity
+/** @addtogroup Object
     @{ */
 
-/** @file qofclass.h
+/** @addtogroup Class
-    @brief API for registering paramters on objects 
-    @author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
-    @author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
-
   This file defines a class messaging system reminiscent of
   traditional OO-style setter and getter interfaces to object 
   properties.  A C-language object can declare a collection
   of setters and getters on itself that can then be used 
   to perform run-time (as opposed to compile-time) bindings 
   to the object.
+
+  To put it differently, a QOF class is a set of parameter
+  getters and setters that are associated with an object type. 
+  Given a pointer to some thing, the setters and getters can
+  be used to get and set values out of that thing.  Note
+  that the pointer to "some thing" need not be a pointer
+  to a QOF Entity or Instance (although QOF classes are
+  more interesting when used with Entities/Instances).
+  What "some thing" is defined entirely by the programmer
+  declaring a new QOF Class.
+
+  Because a QOF Class associates getters and setters with
+  a type, one can then ask, at run time, what paramters
+  are associated with a given type, even if those paramters
+  were not known at compile time.  Thus, a QOF Class is 
+  sort-of like a DynAny implementation.  QOF classes can
+  be used to provide "object introspection", i.e. asking 
+  object to describe itself.
+
+  The QOF Query subsystem depends on QOF classes having been
+  declared; the Query uses the getters to get values associated
+  with particular instances.
+@{ */
+
+/** @file qofclass.h
+    @brief API for registering paramters on objects 
+    @author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
+    @author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
 */
 
 #ifndef QOF_CLASS_H
@@ -172,3 +196,4 @@ QofSetterFunc qof_class_get_parameter_setter (QofIdTypeConst obj_name,
 
 #endif /* QOF_CLASS_H */
 /* @} */
+/* @} */

src/engine/qofgobj.h

@@ -23,20 +23,24 @@
 #ifndef QOF_GOBJ_H
 #define QOF_GOBJ_H
 
-/** @addtogroup GObject
+/** @addtogroup Object
     @{ */
+/** @addtogroup GObject GLib GObjects
+    The API defined in this file allows a user to register any
+    GLib GObject (and any object derived from one, e.g. GTK/Gnome)
+    with the QOF system, as a QOF Object Class.  This allows
+    the QOF Query routines to be used to search over collections
+    of GObjects.
+ 
+    XXX Only GObject properties are searchable, data and other 
+    hanging off the GObject is not.  Fix this. This needs fixing.
+
+@{ */
 /** @file qofgobj.h
     @brief QOF to GLib GObject mapping
     @author Copyright (C) 2004 Linas Vepstas <linas@linas.org>
 */
 
-/** The API defined in this file allows a user to register any
- *  GLib GObject (and any object derived from one, e.g. GTK/Gnome)
- *  with the QOF system so that it becomes searchable.  
- *
- * XXX Only GObject properties are searchable, data and other 
- * hanging off the GObject is not.  Fix this.
- */  
 
 #include <glib-object.h>
 #include <qof/qofbook.h>
@@ -79,4 +83,5 @@ void qof_gobject_register_instance (QofBook *book, QofType, GObject *);
 
 #endif /* QOF_GOBJ_H */
 /** @} */
+/** @} */
 

src/engine/qofid-p.h

@@ -20,6 +20,13 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
+/** @addtogroup Object
+    @{ */
+/** @addtogroup Object_Private
+    Private interfaces, not meant to be used by applications.
+    @{ */
+/** @name  Entity_Private
+    @{ */
 
 #ifndef QOF_ID_P_H
 #define QOF_ID_P_H 
@@ -42,8 +49,11 @@ void qof_entity_set_guid (QofEntity *ent, const GUID *guid);
  */
 void qof_collection_insert_entity (QofCollection *, QofEntity *);
 
-/* reset value of dirty flag */
+/** reset value of dirty flag */
 void qof_collection_mark_clean (QofCollection *);
 void qof_collection_mark_dirty (QofCollection *);
 
+/* @} */
+/* @} */
+/* @} */
 #endif /* QOF_ID_P_H */

src/engine/qofid.h

@@ -24,6 +24,40 @@
 #define QOF_ID_H 
 
 /** @addtogroup Entity 
+    @{ */
+/** @addtogroup Entities
+
+    This file defines an API that adds types to the GUID's.
+    GUID's with types can be used to identify and reference 
+    typed entities.  
+
+    The idea here is that a GUID can be used to uniquely identify
+    some thing.  By adding a type, one can then talk about the 
+    type of thing identified.  By adding a collection, one can
+    then work with a handle to a collection of things of a given
+    type, each uniquely identified by a given ID.  QOF Entities
+    can be used independently of any other part of the system.
+    In particular, Entities can be useful even if one is not using
+    the Query ond Object parts of the QOF system.
+  
+    Identifiers are globally-unique and permanent, i.e., once
+    an entity has been assigned an identifier, it retains that same
+    identifier for its lifetime.
+    Identifiers can be encoded as hex strings. 
+   
+    GUID Identifiers are 'typed' with strings.  The native ids used 
+    by QOF are defined below. An id with type QOF_ID_NONE does not 
+    refer to any entity, although that may change (???). An id with 
+    type QOF_ID_NULL does not refer to any entity, and will never refer
+    to any entity. An identifier with any other type may refer to an
+    actual entity, but that is not guaranteed (??? Huh?).  If an id 
+    does refer to an entity, the type of the entity will match the 
+    type of the identifier. 
+
+    If you have a type name, and you want to have a way of finding
+    a collection that is associated with that type, then you must use
+    Books.
+
  @{ */
 /** @file qofid.h
     @brief QOF entity type identification system 
@@ -31,26 +65,6 @@
     @author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
 */
 
-/** This file defines an API that adds types to the GUID's.
- *  GUID's with types can be used to identify and reference 
- *  typed entities.
- *
- * GUID Identifiers can be used to reference QOF Objects.
- * Identifiers are globally-unique and permanent, i.e., once
- * an entity has been assigned an identifier, it retains that same
- * identifier for its lifetime.
- *
- * Identifiers can be encoded as hex strings. 
- *
- * GUID Identifiers are 'typed' with strings.  The native ids used 
- * by QOF are defined below. An id with type QOF_ID_NONE does not 
- * refer to any entity, although that may change (???). An id with 
- * type QOF_ID_NULL does not refer to any entity, and will never refer
- * to any entity. An identifier with any other type may refer to an
- * actual entity, but that is not guaranteed (??? Huh?).  If an id 
- * does refer to an entity, the type of the entity will match the 
- * type of the identifier. 
- */
 
 #include <string.h>
 #include "guid.h"
@@ -107,17 +121,21 @@ struct QofEntity_s
 	QofCollection  * collection;
 };
 
+/** @name QOF Entity Initialization & Shutdown 
+ @{ */
 /** Initialise the memory associated with an entity */
 void qof_entity_init (QofEntity *, QofIdType, QofCollection *);
                                                                                 
 /** Release the data associated with this entity. Dont actually free
  * the memory associated with the instance. */
 void qof_entity_release (QofEntity *);
+ /* @} */
 
 /* Return the GUID of this entity */
 const GUID * qof_entity_get_guid (QofEntity *);
 
-/** collections of entities */
+/** @name Collections of Entities 
+ @{ */
 QofCollection * qof_collection_new (QofIdType type);
 void qof_collection_destroy (QofCollection *col);
 
@@ -145,8 +163,10 @@ void qof_collection_set_data (QofCollection *col, gpointer user_data);
 
 /* Return value of 'dirty' flag on collection */
 gboolean qof_collection_is_dirty (QofCollection *col);
+/** @} */
 
 
 #endif /* QOF_ID_H */
 /** @} */
+/** @} */
 

src/engine/qofinstance-p.h

@@ -26,38 +26,46 @@
  * Copyright (C) 2003 Linas Vepstas <linas@linas.org>
  */
 
+/** @addtogroup Object
+    @{ */
+/** @addtogroup Object_Private
+    Private interfaces, not meant to be used by applications.
+    @{ */
+/** @name  Instance_Private
+    @{ */
+
 #ifndef QOF_INSTANCE_P_H
 #define QOF_INSTANCE_P_H
 
 #include "qofinstance.h"
 
-struct QofInstance_s
+/**
-{
-/*
  * UNDER CONSTRUCTION!
  * This is mostly scaffolding for now,
  * eventually, it may hold more fields, such as refrence counting...
  *
  */
-   /* Globally unique id identifying this instance */
+struct QofInstance_s
+{
+   /** Globally unique id identifying this instance */
 	QofEntity entity;
 
-   /* The entity_table in which this instance is stored */
+   /** The entity_table in which this instance is stored */
    QofBook * book;
 
-  /* kvp_data is a key-value pair database for storing arbirtary
+  /** kvp_data is a key-value pair database for storing arbirtary
    * information associated with this instance.  
    * See src/engine/kvp_doc.txt for a list and description of the 
    * important keys. */
    KvpFrame *kvp_data;
 
-   /* Keep track of nesting level of begin/end edit calls */
+   /** Keep track of nesting level of begin/end edit calls */
    int    editlevel;
 
-   /* In process of being destroyed */
+   /** In process of being destroyed */
    gboolean  do_free;
 
-   /* This instance has not been saved yet */
+   /** This instance has not been saved yet */
    gboolean  dirty;
 };
 
@@ -66,4 +74,8 @@ void qof_instance_mark_clean (QofInstance *);
 
 void qof_instance_set_slots (QofInstance *, KvpFrame *);
 
+/* @} */
+/* @} */
+/* @} */
+
 #endif /* QOF_INSTANCE_P_H */

src/engine/qofinstance.h

@@ -20,6 +20,12 @@
  *                                                                  *
 \********************************************************************/
 /** @addtogroup Entity
+    @{ */
+/** @addtogroup Instance
+    Qof Instances are a derived type of QofEntity.  The Instance
+    adds some common features and functions that most objects
+    will want to use.
+
     @{ */
 /** @file qofinstance.h 
  *  @brief Object instance holds common fields that most gnucash objects use.
@@ -88,5 +94,6 @@ void qof_instance_gemini (QofInstance *to, QofInstance *from);
  */
 QofInstance * qof_instance_lookup_twin (QofInstance *src, QofBook *book);
 
+/* @} */
 /* @} */
 #endif /* QOF_INSTANCE_H */

src/engine/qofobject-p.h

@@ -18,11 +18,15 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
-/** @addtogroup Entity
+/** @addtogroup Object
+    @{ */
+/** @addtogroup Object_Private
+    Private interfaces, not meant to be used by applications. 
+    @{ */
+/** @name  Objects_Private
     @{ */
 /** @file qofobject-p.h
  * @brief the Core Object Registration/Lookup Private Interface
- *
  * @author Copyright (c) 2001,2002, Derek Atkins <warlord@MIT.EDU>
  */
 
@@ -32,7 +36,7 @@
 #include "qofbook.h"
 #include "qofobject.h"
 
-/* To be called from within the book */
+/** To be called from within the book */
 void qof_object_book_begin (QofBook *book);
 void qof_object_book_end (QofBook *book);
 
@@ -41,3 +45,5 @@ void qof_object_mark_clean (QofBook *book);
 
 #endif /* QOF_OBJECT_P_H_ */
 /** @} */
+/** @} */
+/** @} */

src/engine/qofobject.h

@@ -19,11 +19,24 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
-/** @addtogroup Entity
+/** @addtogroup Object
+    @{ */
+/** @addtogroup Objects
+    QOF Objects provide the means for associating
+    a storage backend to a set of QOF Entities.   While an entity
+    can be though of as an identified instance of some thing,  the
+    QOF Object provides for a way to associate instances with
+    a storage backend.  Storage might be file or SQL storage.
+
+    QOF Objects are also used by the query system .... 
+    
+    XXX todo, we should split out the storage aspects of this 
+    thing from the 'foreach' that query depends on.  These are
+    kinad unrelated concepts.
+
     @{ */
 /** @file qofobject.h
  * @brief the Core Object Registration/Lookup Interface
- *
  * @author Copyright (c) 2001,2002, Derek Atkins <warlord@MIT.EDU>
  */
 
@@ -33,7 +46,7 @@
 #include "qofbook.h"
 #include "qofid.h"
 
-/* Defines the version of the core object object registration
+/** Defines the version of the core object object registration
  * interface.  Only object modules compiled against this version
  * of the interface will load properly
  */
@@ -84,9 +97,11 @@ struct _QofObject
 
 /* -------------------------------------------------------------- */
 
-/** Initialize the object registration subsystem */
+/** @name Initialize the object registration subsystem */
+/** @{ */
 void qof_object_initialize (void);
 void qof_object_shutdown (void);
+/** @} */
 
 /** Invoke the callback 'cb' on every object class definition.
  *  The user_data pointer is passed back to the callback.
@@ -101,11 +116,10 @@ void qof_object_foreach_type (QofForeachTypeCB cb, gpointer user_data);
 void qof_object_foreach (QofIdTypeConst type_name, QofBook *book, 
                          QofEntityForeachCB cb, gpointer user_data);
 
+/** @return a Human-readable string name for on object */
 const char * qof_object_printable (QofIdTypeConst type_name, gpointer obj);
 
 
-/* REGISTRATION AND REG-LOOKUP FUNCTIONS */
-
 /** Register new types of object objects */
 gboolean qof_object_register (const QofObject *object);
 
@@ -132,3 +146,4 @@ void qof_object_foreach_backend (const char *backend_name,
 
 #endif /* QOF_OBJECT_H_ */
 /** @} */
+/** @} */

src/engine/qofquery-deserial.h

@@ -20,15 +20,10 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
-/** @addtogroup Query_XML
+/** @addtogroup Query
     @{ */
 /** @file qofquery-deserial.h
     @brief Convert Qof-Query XML to QofQuery 
-
-    Qof Queries can be convrted to and from XML so that they
-    can be sent from here to there. This file implements the
-    routine needed to convert the XML back into a C struct.
-
     @author Copyright (C) 2004 Linas Vepstas <linas@linas.org>
 */
 
@@ -38,8 +33,15 @@
 #include <qof/qofquery.h>
 #include <libxml/tree.h>
 
+/** @addtogroup XML 
+    Qof Queries can be converted to and from XML so that they
+    can be sent from here to there. This file implements the
+    routine needed to convert the XML back into a C struct.
+
+ @{ */
 /** Given an XML tree, reconstruct and return the equivalent query. */
 QofQuery *qof_query_from_xml (xmlNodePtr);
+/* @} */
 
 #endif /* QOF_QUERY_DESERIAL_H */
 /* @} */

src/engine/qofquery-serialize.h

@@ -20,7 +20,7 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
-/* @addtogroup Query_XML
+/** @addtogroup Query
    @{ */
 /** @file qofquery-serialize.h
     @brief Convert QofQuery to XML
@@ -33,11 +33,14 @@
 #include <qof/qofquery.h>
 #include <libxml/tree.h>
 
+/** @addtogroup XML Serialize Queries to/from XML */
+/* @{ */
 /** Take the query passed as input, and serialize it into XML.
  *  The DTD used will be a very qofquery specific DTD
  *  This is NOT the XQuery XML.
  */
 xmlNodePtr qof_query_to_xml (QofQuery *q);
+/* @} */
 
 #endif /* QOF_QUERY_SERIALIZE_H */
 /* @} */

src/engine/qofquery.h

@@ -20,13 +20,7 @@
  *                                                                  *
 \********************************************************************/
 
-/** @addtogroup Query_Core_API
+/** @addtogroup Query
-    @{ */
-
-/** @file qofquery.h
-    @brief find objects that match a certain expression.
-    @author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
-    @author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
 
 BASIC QUERY API: 
 With this API you can create arbitrary logical
@@ -39,6 +33,12 @@ will handle freeing it.  To make compound queries, make multiple
 simple queries and combine them using qof_query_merge() and the logical
 operations of your choice.
 
+SQL QUERY API: 
+As an alternative to building queries one predicate at a time,
+you can use the SQL query interface.  This interface will accept 
+a string containing an SQL query, parse it, convert it into the
+core representation, and execute it.
+
 STRUCTURE OF A QUERY: A Query is a logical function of any number of
 QueryTerms.  A QueryTerm consists of a C function pointer (the
 Predicate) and a PredicateData structure containing data passed to the
@@ -70,6 +70,12 @@ first to allow the evaluator to completely eliminate accounts from the
 search if there's no chance of them having splits that match.
 (XXX above no longer applies)
 
+ @{ */
+/** @file qofquery.h
+    @brief find objects that match a certain expression.
+    @author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
+    @author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
+
 */
 
 
@@ -106,6 +112,8 @@ typedef enum {
 #define QOF_QUERY_PARAM_ACTIVE  "active" 
 
 /* --------------------------------------------------------- */
+/** @name Query Subsystem Initialization and Shudown  */
+/* @{ */
 /** Subsystem initialization and shutdown. Call init() once 
  *  to initalize the query subsytem; call shutdown() to free
  *  up any resources associated with the query subsystem. 
@@ -114,9 +122,11 @@ typedef enum {
 
 void qof_query_init (void);
 void qof_query_shutdown (void);
+/* @} */
 
 /* --------------------------------------------------------- */
-/** Basic API Functions */
+/** @name Low-Level API Functions */
+/* @{ */
 
 GSList * qof_query_build_param_list (char const *param, ...);
 
@@ -352,5 +362,6 @@ QofIdType qof_query_get_search_for (QofQuery *q);
 /** Return the list of books we're using */
 GList * qof_query_get_books (QofQuery *q);
 
+/* @} */
 #endif /* QOF_QUERYNEW_H */
 /* @} */

src/engine/qofquerycore.h

@@ -21,7 +21,7 @@
  *                                                                  *
 \********************************************************************/
 
-/** @addtogroup Query_Core_Predicates
+/** @addtogroup Query
     @{ */
                                                                                 
 /** @file qofquerycore.h
@@ -138,7 +138,8 @@ struct _QofQueryPredData {
 };
 
 
-/** Core Data Type Predicates */
+/** @name Core Data Type Predicates 
+    @{ */
 QofQueryPredData *qof_query_string_predicate (QofQueryCompare how, 
                                               const char *str,
                                               QofStringMatch options,
@@ -187,3 +188,4 @@ char * qof_query_core_to_string (QofType, gpointer object, QofParam *getter);
 
 #endif /* QOF_QUERYCORE_H */
 /* @} */
+/* @} */

src/engine/qofsession.h

@@ -21,14 +21,9 @@
 \********************************************************************/
 
 /** @addtogroup Backend
- *     @{ */
-/** @file qofsession.h
- * @brief Encapsulates a connection to a backednd (persistent store)
- * @author Copyright (c) 1998, 1999, 2001, 2002 Linas Vepstas <linas@linas.org>
- * @author Copyright (c) 2000 Dave Peticolas
  *
- * FUNCTION:
+ * The QOF Session 
- * Encapsulates a connection to a storage backend.  That is, it
+ * encapsulates a connection to a storage backend.  That is, it
  * manages the connection to a persistant data store; whereas
  * the backend is the thing that performs the actual datastore 
  * access.
@@ -63,7 +58,7 @@
  *    level: i.e. does this user even have the authority to connect
  *    to and open this datastore?
  *
- * A breif note about books & sessions:
+ * A brief note about books & sessions:
  * A book encapsulates the datasets manipulated by GnuCash.  A book
  * holds the actual data.  By contrast, the session mediates the
  * connection between a book (the thing that lives in virtual memory
@@ -80,6 +75,13 @@
  * make that assumption, in order to store the different accounting
  * periods in a clump so that one can be found, given another.
  *
+ *  @{ 
+ */
+
+/** @file qofsession.h
+ * @brief Encapsulates a connection to a backend (persistent store)
+ * @author Copyright (c) 1998, 1999, 2001, 2002 Linas Vepstas <linas@linas.org>
+ * @author Copyright (c) 2000 Dave Peticolas
  */
 
 #ifndef QOF_SESSION_H
@@ -154,14 +156,20 @@ typedef void (*QofPercentageFunc) (const char *message, double percent);
 void qof_session_load (QofSession *session,
 		       QofPercentageFunc percentage_func);
 
-/* XXX session_export really doesn't belong here */
+/** XXX session_export really doesn't belong here */
 gboolean qof_session_export (QofSession *tmp_session,
 			     QofSession *real_session,
 			     QofPercentageFunc percentage_func);
 
+/** @name Session Errors 
+ @{ */
 /** The qof_session_get_error() routine can be used to obtain the reason
  *    for any failure.  Calling this routine returns the current error.
- *
+ */
+QofBackendError qof_session_get_error (QofSession *session);
+const char * qof_session_get_error_message(QofSession *session);
+
+/**
  * The qof_session_pop_error() routine can be used to obtain the reason
  *    for any failure.  Calling this routine resets the error value.  
  *
@@ -171,9 +179,8 @@ gboolean qof_session_export (QofSession *tmp_session,
  *
  *    See qofbackend.h for a listing of returned errors.
  */
-QofBackendError qof_session_get_error (QofSession *session);
-const char * qof_session_get_error_message(QofSession *session);
 QofBackendError qof_session_pop_error (QofSession *session);
+/* @} */
 
 /** The qof_session_add_book() allows additional books to be added to
  *    a session. 
@@ -216,7 +223,10 @@ gboolean qof_session_save_may_clobber_data (QofSession *session);
  *    more than a write to the file of the current AccountGroup & etc.
  *    For the SQL backend, this is typically a no-op (since all data
  *    has already been written out to the database.
- *
+ */
+void     qof_session_save (QofSession *session,
+			   QofPercentageFunc percentage_func);
+/**
  * The qof_session_end() method will release the session lock. For the
  *    file backend, it will *not* save the account group to a file. Thus, 
  *    this method acts as an "abort" or "rollback" primitive.  However,
@@ -224,20 +234,22 @@ gboolean qof_session_save_may_clobber_data (QofSession *session);
  *    been written out before this, and so this routines wouldn't 
  *    roll-back anything; it would just shut the connection.
  */
-void     qof_session_save (QofSession *session,
-			   QofPercentageFunc percentage_func);
 void     qof_session_end  (QofSession *session);
 
+/** @name Event Handling
+ @{ */
 /** The qof_session_events_pending() method will return TRUE if the backend
  *    has pending events which must be processed to bring the engine
  *    up to date with the backend.
- *
+ */
- * The qof_session_process_events() method will process any events indicated
+gboolean qof_session_events_pending (QofSession *session);
+
+/**  The qof_session_process_events() method will process any events indicated
  *    by the qof_session_events_pending() method. It returns TRUE if the
  *    engine was modified while engine events were suspended.
  */
-gboolean qof_session_events_pending (QofSession *session);
 gboolean qof_session_process_events (QofSession *session);
+/* @} */
 
 /** The xaccResolveFilePath() routine is a utility that will accept
  *    a fragmentary filename as input, and resolve it into a fully
@@ -252,7 +264,8 @@ gboolean qof_session_process_events (QofSession *session);
 char * xaccResolveFilePath (const char * filefrag);
 char * xaccResolveURL (const char * pathfrag);
 
-/** Run the RPC Server */
+/** Run the RPC Server 
+ *  @deprecated  will go away */
 void gnc_run_rpc_server (void);
 
 #endif /* QOF_SESSION_H */

src/engine/qofsql.h

@@ -20,7 +20,7 @@
  *                                                                  *
 \********************************************************************/
 
-/** @addtogroup Query_SQL
+/** @addtogroup Query
     @{ */
 /**
     @file qofsql.h
@@ -36,6 +36,8 @@
 #include <qof/qofbook.h>
 #include <qof/qofquery.h>
 
+/** @addtogroup SQL SQL Interface to Query
+  @{ */
 typedef struct _QofSqlQuery QofSqlQuery;
 
 /** Create a new SQL-syntax query machine.
@@ -139,5 +141,6 @@ GList * qof_sql_query_rerun (QofSqlQuery *query);
  */
 void qof_sql_query_set_kvp (QofSqlQuery *, KvpFrame *);
 
+/** @} */
 #endif /* QOF_SQL_QUERY_H */
 /** @} */