[Gnucash-changes] Round one of changes to make doxygen generat nice
docs
Linas Vepstas
linas at cvs.gnucash.org
Thu May 6 22:37:10 EDT 2004
Log Message:
-----------
Round one of changes to make doxygen generat nice docs
Modified Files:
--------------
gnucash/src/engine:
Account.h
FreqSpec.c
FreqSpec.h
Period.h
SX-book.h
SchedXaction.h
TransLog.h
Transaction.h
cap-gains.h
gnc-commodity.h
gnc-pricedb.h
qof.h
Revision Data
-------------
Index: SchedXaction.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/SchedXaction.h,v
retrieving revision 1.32
retrieving revision 1.33
diff -Lsrc/engine/SchedXaction.h -Lsrc/engine/SchedXaction.h -u -r1.32 -r1.33
--- src/engine/SchedXaction.h
+++ src/engine/SchedXaction.h
@@ -18,7 +18,10 @@
* *
\********************************************************************/
/**
- * @addtogroup Engine_SchedXaction
+ * @addtogroup Engine
+ * @{ */
+/**
+ * @addtogroup SchedXaction
* @{ */
/**
* @file SchedXaction.h
@@ -223,4 +226,5 @@
#endif /* XACC_SCHEDXACTION_H */
+/** @} */
/** @} */
Index: Period.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/Period.h,v
retrieving revision 1.17
retrieving revision 1.18
diff -Lsrc/engine/Period.h -Lsrc/engine/Period.h -u -r1.17 -r1.18
--- src/engine/Period.h
+++ src/engine/Period.h
@@ -20,6 +20,8 @@
\********************************************************************/
/** @addtogroup Engine
@{ */
+/** @addtogroup Period Accounting Periods
+ @{ */
/** @file Period.h
* @breif Implement accounting periods, as per design in src/doc/books.txt
* @author Copyright (c) 2001,2003 Linas Vepstas <linas at linas.org>
@@ -182,4 +184,5 @@
void gnc_book_insert_price_clobber (QofBook *book, GNCPrice *prc);
#endif /* XACC_PERIOD_H */
+/** @} */
/** @} */
Index: SX-book.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/SX-book.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -Lsrc/engine/SX-book.h -Lsrc/engine/SX-book.h -u -r1.5 -r1.6
--- src/engine/SX-book.h
+++ src/engine/SX-book.h
@@ -20,7 +20,10 @@
\********************************************************************/
/**
- * @addtogroup Engine_SchedXaction
+ * @addtogroup Engine
+ * @{ */
+/**
+ * @addtogroup SchedXaction
* @{ */
/**
* @file SX-book.h
@@ -56,4 +59,5 @@
#endif /* GNC_SX_BOOK_H */
+/** @} */
/** @} */
Index: FreqSpec.c
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/FreqSpec.c,v
retrieving revision 1.36
retrieving revision 1.37
diff -Lsrc/engine/FreqSpec.c -Lsrc/engine/FreqSpec.c -u -r1.36 -r1.37
--- src/engine/FreqSpec.c
+++ src/engine/FreqSpec.c
@@ -1,17 +1,17 @@
/********************************************************************\
- * FreqSpec.c -- Frequency specifier implementation. *
- * Copyright (C) 2001 Joshua Sled <jsled at asynchronous.org> *
- * Copyright (C) 2001 Ben Stanley <bds02 at uow.edu.au> *
- * *
+ * FreqSpec.c -- Frequency specifier implementation. *
+ * Copyright (C) 2001 Joshua Sled <jsled at asynchronous.org> *
+ * Copyright (C) 2001 Ben Stanley <bds02 at uow.edu.au> *
+ * *
* 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 *
- * the License, or (at your option) any later version. *
- * *
+ * the License, or (at your option) any later version. *
+ * *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
- * GNU General Public License for more details. *
+ * GNU General Public License for more details. *
* *
* You should have received a copy of the GNU General Public License*
* along with this program; if not, contact: *
Index: cap-gains.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/cap-gains.h,v
retrieving revision 1.6
retrieving revision 1.7
diff -Lsrc/engine/cap-gains.h -Lsrc/engine/cap-gains.h -u -r1.6 -r1.7
--- src/engine/cap-gains.h
+++ src/engine/cap-gains.h
@@ -21,11 +21,8 @@
/** @addtogroup Engine
* @{ */
-/** @file cap-gains.h
- * @breif Utilities to Automatically Compute Capital Gains/Losses.
- * @author Created by Linas Vepstas August 2003
- * @author Copyright (c) 2003 Linas Vepstas <linas at linas.org>
- *
+
+/** @addtogroup CapGains Cap Gains
* This file implements the various routines to automatically
* compute and handle Cap Gains/Losses resulting from trading
* activities. Some of these routines might have broader
@@ -38,6 +35,12 @@
* This code does not currently handle tax distinctions, e.g
* the different tax treatment that short-term and long-term
* cap gains have.
+ * @{ */
+
+/** @file cap-gains.h
+ * @breif Utilities to Automatically Compute Capital Gains/Losses.
+ * @author Created by Linas Vepstas August 2003
+ * @author Copyright (c) 2003 Linas Vepstas <linas at linas.org>
*/
#ifndef XACC_CAP_GAINS_H
@@ -186,6 +189,7 @@
void xaccLotComputeCapGains (GNCLot *lot, Account *gain_acc);
#endif /* XACC_CAP_GAINS_H */
+/** @} */
/** @} */
/* =========================== END OF FILE ======================= */
Index: TransLog.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/TransLog.h,v
retrieving revision 1.11
retrieving revision 1.12
diff -Lsrc/engine/TransLog.h -Lsrc/engine/TransLog.h -u -r1.11 -r1.12
--- src/engine/TransLog.h
+++ src/engine/TransLog.h
@@ -20,13 +20,23 @@
/** @addtogroup Engine
@{ */
+/** @addtogroup TransLog Transaction Logging
+ The transaction logging mechanism provides a very simple,
+ low-level logging of user input to a file. The goal of
+ the transaction logger is to provide mechanism of last resort
+ for recovering lost user data in the event of a crash.
+
+ Ideally, the storage backends should provide a robust journaling,
+ logging and crash-recovery mechanism. But just in case they
+ don't, or it didn't work, this mechanism provides a "Plan B"
+ by providing a low-tech, fool-proof, simple logging system
+ that can be used to recover user input.
+ There are some simple command-line tools that will read a log
+ and replay it.
+
+ @{ */
/** @file TransLog.h
@brief API for the transaction logger
-*
- * The logfiles are useful for tracing, journalling, error recovery.
- * Note that the current support for journalling is at best
- * embryonic, at worst, is dangerous by setting the wrong expectations.
- *
@author Copyright (C) 1998 Linas Vepstas
*/
@@ -68,5 +78,6 @@
void xaccLogSetBaseName (const char *);
#endif /* XACC_TRANS_LOG_H */
+/** @} */
/** @} */
Index: qof.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/qof.h,v
retrieving revision 1.4
retrieving revision 1.5
diff -Lsrc/engine/qof.h -Lsrc/engine/qof.h -u -r1.4 -r1.5
--- src/engine/qof.h
+++ src/engine/qof.h
@@ -21,6 +21,43 @@
#ifndef QOF_H_
#define QOF_H_
+/** @defgroup QOF Query Object Framework */
+/** @{ */
+
+/**
+ @addtogroup Date Date: Date and Time Printing, Parsing and Manipulation
+ @ingroup QOF
+*/
+/**
+ @addtogroup Entity Entity: Types, Identity and Instance Framework
+ @ingroup QOF
+
+*/
+/**
+ @addtogroup KVP KVP: Key-Value Pairs
+ @ingroup QOF
+*/
+/**
+ @addtogroup Numeric Numeric: Rational Number Handling w/ Rounding Error Control
+ @ingroup QOF
+*/
+/**
+ @addtogroup Object Object: Dynamic Object Class Framework
+ @ingroup QOF
+*/
+/**
+ @addtogroup Query Query: Querying for Objects
+ @ingroup QOF
+*/
+/**
+ @addtogroup Trace Trace: Error Reporting and Debugging
+ @ingroup QOF
+*/
+/**
+ @addtogroup Utilities Misc Utilities
+ @ingroup QOF
+*/
+/** @} */
#include "qof/gnc-date.h"
#include "qof/gnc-engine-util.h"
Index: Transaction.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/Transaction.h,v
retrieving revision 1.159
retrieving revision 1.160
diff -Lsrc/engine/Transaction.h -Lsrc/engine/Transaction.h -u -r1.159 -r1.160
--- src/engine/Transaction.h
+++ src/engine/Transaction.h
@@ -19,6 +19,8 @@
\********************************************************************/
/** @addtogroup Engine
@{ */
+/** @addtogroup Transaction Financial Transactions
+ @{ */
/** @file Transaction.h
@brief API for Transactions and Splits (journal entries)
@author Copyright (C) 1997 Robin D. Clark
@@ -873,4 +875,5 @@
#define xaccTransGetSlots(X) qof_instance_get_slots (QOF_INSTANCE(X))
#endif /* XACC_TRANSACTION_H */
+/** @} */
/** @} */
Index: gnc-pricedb.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/gnc-pricedb.h,v
retrieving revision 1.39
retrieving revision 1.40
diff -Lsrc/engine/gnc-pricedb.h -Lsrc/engine/gnc-pricedb.h -u -r1.39 -r1.40
--- src/engine/gnc-pricedb.h
+++ src/engine/gnc-pricedb.h
@@ -37,12 +37,7 @@
/** @addtogroup Engine
@{ */
-/**********************************************************************/
-/** @file gnc-pricedb.h
- @author Copyright (C) 2001 Rob Browning
- @author Copyright (C) 2001,2003 Linas Vepstas <linas at linas.org>
- @brief a simple price database for gnucash
-
+/** @addtogroup PriceDB Price Database
The PriceDB is intended to be a database of price quotes, or more
specifically, a database of GNCPrices. For the time being, it is
still a fairly simple database supporting only fairly simple
@@ -54,12 +49,14 @@
Every QofBook contains a GNCPriceDB, accessable via
gnc_book_get_pricedb.
+ \warning The PriceDB does not currently use the object
+ system used elsewhere in the GnuCash Engine, i.e. it does
+ not use GUISD's, Entities and Collections. Its should.
+ In particular, this means that currently prices cannot
+ be queried with the same emchanism as everything else.
*/
-/* *********************************************************************/
-
-/** GNCPrice:
-
+/** @addtogroup Price Prices
Each price in the database represents an "instantaneous" quote for
a given commodity with respect to another commodity. For example,
a given price might represent the value of LNUX in USD on
@@ -116,13 +113,24 @@
exception of the commodity field which just stores the pointer
given. It is assumed that commodities are a global resource and
are pointer unique.
+ */
+/** @file gnc-pricedb.h
+ @author Copyright (C) 2001 Rob Browning
+ @author Copyright (C) 2001,2003 Linas Vepstas <linas at linas.org>
+ @brief a simple price database for gnucash
+*/
+
+/* ================================================================ */
+
+/** @addtogroup Price Prices
+ @{ */
- */
/** */
typedef struct gnc_price_lookup_s GNCPriceLookup;
-/****************/
-/* constructors */
+/* ------------------ */
+/** @name Constructors
+ @{ */
/** gnc_price_create - returns a newly allocated and initialized price
with a reference count of 1. */
@@ -132,9 +140,11 @@
content-wise duplicate of the given price, p. The returned clone
will have a reference count of 1. */
GNCPrice *gnc_price_clone(GNCPrice* p, QofBook *book);
+/** @} */
-/*********************/
-/* memory management */
+/* ------------------ */
+/** @name Memory Management
+ @{ */
/** gnc_price_ref - indicate your need for a given price to stick
around (i.e. increase its reference count by 1). */
@@ -143,9 +153,11 @@
/** gnc_price_ref - indicate you're finished with a price
(i.e. decrease its reference count by 1). */
void gnc_price_unref(GNCPrice *p);
+/** @} */
-/***********/
-/* setters */
+/* ------------------ */
+/** @name Setters
+ @{ */
/* As mentioned above, all of the setters store copies of the data
* given, with the exception of the commodity field which just stores
@@ -167,9 +179,11 @@
void gnc_price_set_type(GNCPrice *p, const char* type);
void gnc_price_set_value(GNCPrice *p, gnc_numeric value);
void gnc_price_set_version(GNCPrice *p, gint32 versn);
+/** @} */
-/***********/
-/* getters */
+/* ------------------ */
+/** @name Getters
+ @{ */
/** As mentioned above all of the getters return data that's internal
to the GNCPrice, not copies, so don't free these values. */
@@ -186,10 +200,10 @@
#define gnc_price_get_guid(X) qof_entity_get_guid(QOF_ENTITY(X))
#define gnc_price_return_guid(X) (*(qof_entity_get_guid(QOF_ENTITY(X))))
#define gnc_price_get_book(X) qof_instance_get_book(QOF_INSTANCE(X))
+/** @} */
-/* ******************************************************************** */
-/** GNCPrice lists:
-
+/* ================================================================ */
+/** @name GNCPrice lists
The database communicates multiple prices in and out via gnc price
lists. These are just time sorted GLists of GNCPrice pointers.
Functions for manipulating these lists are provided. These
@@ -198,7 +212,7 @@
held in a given list. I.e. insert "refs" the prices being
inserted, remove and destroy "unref" the prices that will no
longer be referred to by the list.
-
+ @{
*/
/** gnc_price_list_insert - insert a price into the given list, calling
@@ -214,10 +228,10 @@
void gnc_price_list_destroy(GList *prices);
gboolean gnc_price_list_equal(GList *prices1, GList *prices2);
+/** @} */
-/* ******************************************************************** */
-/** GNCPriceDB
-
+/* ================================================================ */
+/** @addtogroup PriceDB
Whenever a you store a price in the pricedb, the pricedb adds its
own reference to the price, so you can safely unref that price after
inserting it into the DB if you're finished with it otherwise.
@@ -226,11 +240,11 @@
or in a price list, the price will have had a ref added for you, so
you only need to unref the price(s) when you're finished with
it/them.
-
+ @{
*/
+/** Data type */
typedef struct gnc_price_db_s GNCPriceDB;
-
/** gnc_pricedb_create - create a new pricedb. Normally you won't need
this; you will get the pricedb via gnc_pricedb_get_db. */
GNCPriceDB * gnc_pricedb_create(QofBook *book);
@@ -379,5 +393,8 @@
#define PRICE_VALUE "price-value"
/**@}*/
+/** @} */
+
#endif /* GNC_PRICEDB_H */
+/** @} */
/** @} */
Index: gnc-commodity.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/gnc-commodity.h,v
retrieving revision 1.30
retrieving revision 1.31
diff -Lsrc/engine/gnc-commodity.h -Lsrc/engine/gnc-commodity.h -u -r1.30 -r1.31
--- src/engine/gnc-commodity.h
+++ src/engine/gnc-commodity.h
@@ -22,15 +22,22 @@
/** @addtogroup Engine
@{ */
+/** @addtogroup Commodity Commodities
+ A commodity is something of value that is easily tradeable or
+ sellable; for example, currencies, stocks, bonds, grain,
+ copper, and oil are all commodities. This file provides
+ an API for defining a commodities, and for working with
+ collections of commodities. All GnuCash financial transactions
+ must identify the commodity that is being traded.
+
+ @warning The system used here does not follow the object
+ handling and identification system (GUID's, Entities, etc.)
+ that the other parts of GnuCash use. The API really should be
+ ported over. This would allow us to get rid of the
+ commodity table reoutines defined below.
+
+ @{ */
/** @file gnc-commodity.h
- *
- * This file contains the functions to manipulate two different
- * objects. These are an object of type gnc_commodity, and an object
- * of type gnc_commodity_table. The gnc_commodity object corresponds
- * one-to-one with some type of tradable commodity; a currency, a
- * stock, a mutual fund, etc. The gnc_commodity_table object is a
- * database containing objects of type gnc_commodity.
- *
* @brief Commodity handling public routines
* @author Copyright (C) 2000 Bill Gribble
* @author Copyright (C) 2001 Linas Vepstas <linas at linas.org>
@@ -783,4 +790,5 @@
#endif /* GNC_COMMODITY_H */
+/** @} */
/** @} */
Index: Account.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/Account.h,v
retrieving revision 1.134
retrieving revision 1.135
diff -Lsrc/engine/Account.h -Lsrc/engine/Account.h -u -r1.134 -r1.135
--- src/engine/Account.h
+++ src/engine/Account.h
@@ -19,6 +19,8 @@
\********************************************************************/
/** @addtogroup Engine
@{ */
+/** @addtogroup Account
+ @{ */
/** @file Account.h
@brief Account handling public routines
@author Copyright (C) 1997 Robin D. Clark
@@ -727,4 +729,5 @@
#define ACCOUNT_MATCH_ALL_TYPE "account-match-all"
#endif /* XACC_ACCOUNT_H */
+/** @} */
/** @} */
Index: FreqSpec.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/FreqSpec.h,v
retrieving revision 1.18
retrieving revision 1.19
diff -Lsrc/engine/FreqSpec.h -Lsrc/engine/FreqSpec.h -u -r1.18 -r1.19
--- src/engine/FreqSpec.h
+++ src/engine/FreqSpec.h
@@ -17,7 +17,9 @@
* Boston, MA 02111-1307, USA gnu at gnu.org *
* *
\********************************************************************/
-/** @addtogroup Engine_SchedXaction
+/** @addtogroup Engine
+ @{ */
+/** @addtogroup FreqSpec Frequency Specification
@{ */
/** @file FreqSpec.h
@brief Period / Date Frequency Specification
@@ -232,4 +234,5 @@
int gnc_freq_spec_compare( FreqSpec *a, FreqSpec *b );
#endif /* XACC_FREQSPEC_H */
+/**@}*/
/**@}*/
More information about the Gnucash-changes
mailing list