[Gnucash-changes] update documentation structure so that doxygen
generates nice output
Linas Vepstas
linas at cvs.gnucash.org
Thu May 6 10:42:30 EDT 2004
Log Message:
-----------
update documentation structure so that doxygen generates nice output
Modified Files:
--------------
gnucash/src/engine:
gnc-date.h
gnc-engine-util.h
gnc-numeric.h
gnc-trace.h
guid.h
kvp-util-p.h
kvp-util.h
kvp_frame.h
qofbackend-p.h
qofbackend.h
qofbook-p.h
qofbook.h
qofclass-p.h
qofclass.h
qofgobj.h
qofid-p.h
qofid.h
qofinstance-p.h
qofinstance.h
qofobject-p.h
qofobject.h
qofquery-deserial.h
qofquery-serialize.h
qofquery.h
qofquerycore.h
qofsession.h
qofsql.h
Revision Data
-------------
Index: qofsql.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofsql.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -Lsrc/engine/qofsql.h -Lsrc/engine/qofsql.h -u -r1.5 -r1.6
--- src/engine/qofsql.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 @@
*/
void qof_sql_query_set_kvp (QofSqlQuery *, KvpFrame *);
+/** @} */
#endif /* QOF_SQL_QUERY_H */
/** @} */
Index: qofquery.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofquery.h,v
retrieving revision 1.10
retrieving revision 1.11
diff -Lsrc/engine/qofquery.h -Lsrc/engine/qofquery.h -u -r1.10 -r1.11
--- src/engine/qofquery.h
+++ src/engine/qofquery.h
@@ -20,13 +20,7 @@
* *
\********************************************************************/
-/** @addtogroup Query_Core_API
- @{ */
-
-/** @file qofquery.h
- @brief find objects that match a certain expression.
- @author Copyright (C) 2002 Derek Atkins <warlord at MIT.EDU>
- @author Copyright (C) 2003 Linas Vepstas <linas at linas.org>
+/** @addtogroup Query
BASIC QUERY API:
With this API you can create arbitrary logical
@@ -39,6 +33,12 @@
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 @@
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 at MIT.EDU>
+ @author Copyright (C) 2003 Linas Vepstas <linas at linas.org>
+
*/
@@ -106,6 +112,8 @@
#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 @@
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 @@
/** Return the list of books we're using */
GList * qof_query_get_books (QofQuery *q);
+/* @} */
#endif /* QOF_QUERYNEW_H */
-/* @} */
+/* @} */
Index: qofid.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofid.h,v
retrieving revision 1.10
retrieving revision 1.11
diff -Lsrc/engine/qofid.h -Lsrc/engine/qofid.h -u -r1.10 -r1.11
--- src/engine/qofid.h
+++ src/engine/qofid.h
@@ -23,34 +23,48 @@
#ifndef QOF_ID_H
#define QOF_ID_H
-/** @addtogroup Entity
+/** @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
@author Copyright (C) 2000 Dave Peticolas <peticola at cs.ucdavis.edu>
@author Copyright (C) 2003 Linas Vepstas <linas at 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 @@
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 @@
/* Return value of 'dirty' flag on collection */
gboolean qof_collection_is_dirty (QofCollection *col);
+/** @} */
#endif /* QOF_ID_H */
+/** @} */
/** @} */
Index: gnc-trace.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/gnc-trace.h,v
retrieving revision 1.11
retrieving revision 1.12
diff -Lsrc/engine/gnc-trace.h -Lsrc/engine/gnc-trace.h -u -r1.11 -r1.12
--- src/engine/gnc-trace.h
+++ src/engine/gnc-trace.h
@@ -22,7 +22,7 @@
* Author: Linas Vepstas (linas at linas.org) *
\********************************************************************/
-/** @addtogroup Engine
+/** @addtogroup Trace
@{ */
/** @file gnc-trace.h
@@ -133,11 +133,13 @@
* 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 @@
} \
}
+/** 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 @@
} \
}
+/** 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 @@
} \
}
+/** 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 @@
} \
}
+/** 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 @@
} \
}
+/** 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 @@
} \
}
+/** 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 @@
#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 @@
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, \
Index: qofid-p.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofid-p.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -Lsrc/engine/qofid-p.h -Lsrc/engine/qofid-p.h -u -r1.5 -r1.6
--- src/engine/qofid-p.h
+++ src/engine/qofid-p.h
@@ -20,6 +20,13 @@
* Boston, MA 02111-1307, USA gnu at 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_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 */
Index: qofquerycore.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofquerycore.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -Lsrc/engine/qofquerycore.h -Lsrc/engine/qofquerycore.h -u -r1.14 -r1.15
--- src/engine/qofquerycore.h
+++ src/engine/qofquerycore.h
@@ -21,7 +21,7 @@
* *
\********************************************************************/
-/** @addtogroup Query_Core_Predicates
+/** @addtogroup Query
@{ */
/** @file qofquerycore.h
@@ -138,7 +138,8 @@
};
-/** Core Data Type Predicates */
+/** @name Core Data Type Predicates
+ @{ */
QofQueryPredData *qof_query_string_predicate (QofQueryCompare how,
const char *str,
QofStringMatch options,
@@ -186,4 +187,5 @@
char * qof_query_core_to_string (QofType, gpointer object, QofParam *getter);
#endif /* QOF_QUERYCORE_H */
+/* @} */
/* @} */
Index: qofobject-p.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofobject-p.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -Lsrc/engine/qofobject-p.h -Lsrc/engine/qofobject-p.h -u -r1.5 -r1.6
--- src/engine/qofobject-p.h
+++ src/engine/qofobject-p.h
@@ -18,11 +18,15 @@
* Boston, MA 02111-1307, USA gnu at 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 at 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);
@@ -40,4 +44,6 @@
void qof_object_mark_clean (QofBook *book);
#endif /* QOF_OBJECT_P_H_ */
+/** @} */
+/** @} */
/** @} */
Index: qofbackend.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofbackend.h,v
retrieving revision 1.6
retrieving revision 1.7
diff -Lsrc/engine/qofbackend.h -Lsrc/engine/qofbackend.h -u -r1.6 -r1.7
--- src/engine/qofbackend.h
+++ src/engine/qofbackend.h
@@ -18,17 +18,22 @@
* Boston, MA 02111-1307, USA gnu at gnu.org *
* *
\********************************************************************/
-/** @addtogroup Backend
+/** @addtogroup Object
@{ */
-/** @file qofbackend.h
- @brief api for data storage Backend
- *
- The 'backend' is a pseudo-object providing an interface between the
+/** @addtogroup Backend
+ The QOF 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 at linas.org>
*/
@@ -105,4 +110,5 @@
typedef void (*QofBePercentageFunc) (const char *message, double percent);
#endif /* QOF_BACKEND_H */
+/**@}*/
/**@}*/
Index: qofinstance.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofinstance.h,v
retrieving revision 1.11
retrieving revision 1.12
diff -Lsrc/engine/qofinstance.h -Lsrc/engine/qofinstance.h -u -r1.11 -r1.12
--- src/engine/qofinstance.h
+++ src/engine/qofinstance.h
@@ -21,6 +21,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 @@
*/
QofInstance * qof_instance_lookup_twin (QofInstance *src, QofBook *book);
+/* @} */
/* @} */
#endif /* QOF_INSTANCE_H */
Index: gnc-engine-util.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/gnc-engine-util.h,v
retrieving revision 1.42
retrieving revision 1.43
diff -Lsrc/engine/gnc-engine-util.h -Lsrc/engine/gnc-engine-util.h -u -r1.42 -r1.43
--- src/engine/gnc-engine-util.h
+++ src/engine/gnc-engine-util.h
@@ -19,7 +19,7 @@
* Boston, MA 02111-1307, USA gnu at gnu.org *
\********************************************************************/
-/** @addtogroup Engine
+/** @addtogroup Utilities
@{ */
/** @file gnc-engine-util.h
@brief GnuCash engine utility functions
@@ -130,7 +130,7 @@
* 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);
Index: gnc-numeric.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/gnc-numeric.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -Lsrc/engine/gnc-numeric.h -Lsrc/engine/gnc-numeric.h -u -r1.14 -r1.15
--- src/engine/gnc-numeric.h
+++ 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 @@
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;
Index: kvp-util.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/kvp-util.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -Lsrc/engine/kvp-util.h -Lsrc/engine/kvp-util.h -u -r1.3 -r1.4
--- src/engine/kvp-util.h
+++ src/engine/kvp-util.h
@@ -20,19 +20,26 @@
* Boston, MA 02111-1307, USA gnu at 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 */
Index: qofbook.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofbook.h,v
retrieving revision 1.10
retrieving revision 1.11
diff -Lsrc/engine/qofbook.h -Lsrc/engine/qofbook.h -u -r1.10 -r1.11
--- src/engine/qofbook.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 at 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")
- * Encapsulate all the information about a dataset.
- * See src/docs/books.txt for implementation overview.
+ * @brief Encapsulate all the information about a dataset.
*
- * HISTORY:
- * Created by Linas Vepstas December 1998
* @author Copyright (c) 1998, 1999, 2001, 2003 Linas Vepstas <linas at linas.org>
* @author Copyright (c) 2000 Dave Peticolas
*/
@@ -139,4 +146,5 @@
#define qof_book_get_guid(X) qof_entity_get_guid (QOF_ENTITY(X))
#endif /* QOF_BOOK_H */
+/** @} */
/** @} */
Index: kvp_frame.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/kvp_frame.h,v
retrieving revision 1.35
retrieving revision 1.36
diff -Lsrc/engine/kvp_frame.h -Lsrc/engine/kvp_frame.h -u -r1.35 -r1.36
--- src/engine/kvp_frame.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 at linas.org>
-*/
-
-#ifndef KVP_FRAME_H
-#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
+ * 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()
- * routine or one of its brothers. Most of the other routines provide
- * only low-level access.
- */
+ * To set a value into a frame, you will want to use one of the
+ * kvp_frame_set_xxx() routines. Most of the other routines provide
+ * 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 at 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
Index: qofsession.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofsession.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -Lsrc/engine/qofsession.h -Lsrc/engine/qofsession.h -u -r1.5 -r1.6
--- src/engine/qofsession.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 at linas.org>
- * @author Copyright (c) 2000 Dave Peticolas
*
- * FUNCTION:
- * Encapsulates a connection to a storage backend. That is, it
+ * The QOF Session
+ * 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 at linas.org>
+ * @author Copyright (c) 2000 Dave Peticolas
*/
#ifndef QOF_SESSION_H
@@ -154,14 +156,20 @@
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 @@
*
* 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 @@
* 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 @@
* 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 @@
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 */
Index: qofquery-serialize.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofquery-serialize.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -Lsrc/engine/qofquery-serialize.h -Lsrc/engine/qofquery-serialize.h -u -r1.2 -r1.3
--- src/engine/qofquery-serialize.h
+++ src/engine/qofquery-serialize.h
@@ -20,7 +20,7 @@
* Boston, MA 02111-1307, USA gnu at 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 */
/* @} */
Index: qofquery-deserial.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofquery-deserial.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -Lsrc/engine/qofquery-deserial.h -Lsrc/engine/qofquery-deserial.h -u -r1.2 -r1.3
--- src/engine/qofquery-deserial.h
+++ src/engine/qofquery-deserial.h
@@ -20,15 +20,10 @@
* Boston, MA 02111-1307, USA gnu at 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 at 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 */
/* @} */
Index: qofinstance-p.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofinstance-p.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -Lsrc/engine/qofinstance-p.h -Lsrc/engine/qofinstance-p.h -u -r1.2 -r1.3
--- src/engine/qofinstance-p.h
+++ src/engine/qofinstance-p.h
@@ -26,38 +26,46 @@
* Copyright (C) 2003 Linas Vepstas <linas at 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;
};
@@ -65,5 +73,9 @@
void qof_instance_mark_clean (QofInstance *);
void qof_instance_set_slots (QofInstance *, KvpFrame *);
+
+/* @} */
+/* @} */
+/* @} */
#endif /* QOF_INSTANCE_P_H */
Index: qofbackend-p.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofbackend-p.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -Lsrc/engine/qofbackend-p.h -Lsrc/engine/qofbackend-p.h -u -r1.2 -r1.3
--- src/engine/qofbackend-p.h
+++ src/engine/qofbackend-p.h
@@ -21,21 +21,20 @@
* Boston, MA 02111-1307, USA gnu at gnu.org *
* *
\********************************************************************/
-
-/*
- * FILE:
- * 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.
- *
- */
+/** @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
+ 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 @@
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 @@
*/
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 */
Index: qofclass-p.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofclass-p.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -Lsrc/engine/qofclass-p.h -Lsrc/engine/qofclass-p.h -u -r1.1 -r1.2
--- src/engine/qofclass-p.h
+++ src/engine/qofclass-p.h
@@ -20,6 +20,13 @@
* Boston, MA 02111-1307, USA gnu at 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 @@
QofSortFunc qof_class_get_default_sort (QofIdTypeConst obj_name);
+/* @} */
+/* @} */
+/* @} */
#endif /* QOF_CLASSP_H */
Index: kvp-util-p.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/kvp-util-p.h,v
retrieving revision 1.9
retrieving revision 1.10
diff -Lsrc/engine/kvp-util-p.h -Lsrc/engine/kvp-util-p.h -u -r1.9 -r1.10
--- src/engine/kvp-util-p.h
+++ 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 @@
void gnc_kvp_bag_remove_frame (KvpFrame *root, const char *path,
KvpFrame *fr);
+/* @} */
+/* @} */
/* @} */
#endif /* XACC_KVP_UTIL_P_H */
Index: qofgobj.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofgobj.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -Lsrc/engine/qofgobj.h -Lsrc/engine/qofgobj.h -u -r1.2 -r1.3
--- src/engine/qofgobj.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 at 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>
@@ -78,5 +82,6 @@
void qof_gobject_register_instance (QofBook *book, QofType, GObject *);
#endif /* QOF_GOBJ_H */
+/** @} */
/** @} */
Index: gnc-date.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/gnc-date.h,v
retrieving revision 1.9
retrieving revision 1.10
diff -Lsrc/engine/gnc-date.h -Lsrc/engine/gnc-date.h -u -r1.9 -r1.10
--- src/engine/gnc-date.h
+++ src/engine/gnc-date.h
@@ -17,19 +17,9 @@
* Boston, MA 02111-1307, USA gnu at 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 at cs.hmc.edu>
@author Copyright (C) 1998-2001,2003 Linas Vepstas <linas at linas.org>
*/
+/* @{
+ @file gnc-date.h
+ @brief Date and Time handling routines
+*/
+
#ifndef GNC_DATE_H
#define GNC_DATE_H
Index: guid.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/guid.h,v
retrieving revision 1.21
retrieving revision 1.22
diff -Lsrc/engine/guid.h -Lsrc/engine/guid.h -u -r1.21 -r1.22
--- src/engine/guid.h
+++ 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 @@
} 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 @@
GHashTable *guid_hash_table_new(void);
+/* @} */
/* @} */
#endif
Index: qofclass.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofclass.h,v
retrieving revision 1.6
retrieving revision 1.7
diff -Lsrc/engine/qofclass.h -Lsrc/engine/qofclass.h -u -r1.6 -r1.7
--- src/engine/qofclass.h
+++ src/engine/qofclass.h
@@ -20,20 +20,44 @@
* *
\********************************************************************/
-/** @addtogroup Entity
+/** @addtogroup Object
@{ */
-/** @file qofclass.h
- @brief API for registering paramters on objects
- @author Copyright (C) 2002 Derek Atkins <warlord at MIT.EDU>
- @author Copyright (C) 2003 Linas Vepstas <linas at linas.org>
-
+/** @addtogroup Class
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 at MIT.EDU>
+ @author Copyright (C) 2003 Linas Vepstas <linas at linas.org>
*/
#ifndef QOF_CLASS_H
@@ -171,4 +195,5 @@
#endif /* QOF_CLASS_H */
+/* @} */
/* @} */
Index: qofobject.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofobject.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -Lsrc/engine/qofobject.h -Lsrc/engine/qofobject.h -u -r1.14 -r1.15
--- src/engine/qofobject.h
+++ src/engine/qofobject.h
@@ -19,11 +19,24 @@
* Boston, MA 02111-1307, USA gnu at 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 at 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 @@
/* -------------------------------------------------------------- */
-/** 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 (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);
@@ -131,4 +145,5 @@
gpointer user_data);
#endif /* QOF_OBJECT_H_ */
+/** @} */
/** @} */
Index: qofbook-p.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qofbook-p.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -Lsrc/engine/qofbook-p.h -Lsrc/engine/qofbook-p.h -u -r1.5 -r1.6
--- src/engine/qofbook-p.h
+++ src/engine/qofbook-p.h
@@ -19,7 +19,13 @@
* Boston, MA 02111-1307, USA gnu at 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 */
- guint32 idata; /* used by the sql backend for kvp management */
+ /** Backend private expansion data */
+ 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_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 */
More information about the Gnucash-changes
mailing list