From 06fae54699f2a09d41fe807b9e94fa5b77a6450e Mon Sep 17 00:00:00 2001 From: Linas Vepstas Date: Fri, 7 May 2004 02:36:40 +0000 Subject: [PATCH] Round one of changes to make doxygen generat nice docs git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@9940 57a11ea4-9604-0410-9ed3-97b8803252fd --- src/engine/Account.h | 3 ++ src/engine/FreqSpec.c | 14 ++++---- src/engine/FreqSpec.h | 5 ++- src/engine/Period.h | 3 ++ src/engine/SX-book.h | 6 +++- src/engine/SchedXaction.h | 6 +++- src/engine/TransLog.h | 21 ++++++++--- src/engine/Transaction.h | 3 ++ src/engine/cap-gains.h | 14 +++++--- src/engine/gnc-commodity.h | 24 ++++++++----- src/engine/gnc-pricedb.h | 73 +++++++++++++++++++++++--------------- src/engine/qof.h | 37 +++++++++++++++++++ 12 files changed, 153 insertions(+), 56 deletions(-) diff --git a/src/engine/Account.h b/src/engine/Account.h index dc88739c96..d0a1cbe1ab 100644 --- a/src/engine/Account.h +++ b/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 @@ -728,3 +730,4 @@ const char * dxaccAccountGetQuoteTZ (Account *account); #endif /* XACC_ACCOUNT_H */ /** @} */ +/** @} */ diff --git a/src/engine/FreqSpec.c b/src/engine/FreqSpec.c index e80f3ea0fd..4b64e413ce 100644 --- a/src/engine/FreqSpec.c +++ b/src/engine/FreqSpec.c @@ -1,17 +1,17 @@ /********************************************************************\ - * FreqSpec.c -- Frequency specifier implementation. * - * Copyright (C) 2001 Joshua Sled * - * Copyright (C) 2001 Ben Stanley * - * * + * FreqSpec.c -- Frequency specifier implementation. * + * Copyright (C) 2001 Joshua Sled * + * Copyright (C) 2001 Ben Stanley * + * * * 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: * diff --git a/src/engine/FreqSpec.h b/src/engine/FreqSpec.h index 0bf4bac045..7eaa86f350 100644 --- a/src/engine/FreqSpec.h +++ b/src/engine/FreqSpec.h @@ -17,7 +17,9 @@ * Boston, MA 02111-1307, USA gnu@gnu.org * * * \********************************************************************/ -/** @addtogroup Engine_SchedXaction +/** @addtogroup Engine + @{ */ +/** @addtogroup FreqSpec Frequency Specification @{ */ /** @file FreqSpec.h @brief Period / Date Frequency Specification @@ -233,3 +235,4 @@ int gnc_freq_spec_compare( FreqSpec *a, FreqSpec *b ); #endif /* XACC_FREQSPEC_H */ /**@}*/ +/**@}*/ diff --git a/src/engine/Period.h b/src/engine/Period.h index b6d299a3eb..394b6dc8ef 100644 --- a/src/engine/Period.h +++ b/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 @@ -183,3 +185,4 @@ void gnc_book_insert_price_clobber (QofBook *book, GNCPrice *prc); #endif /* XACC_PERIOD_H */ /** @} */ +/** @} */ diff --git a/src/engine/SX-book.h b/src/engine/SX-book.h index 208031925c..674b45c188 100644 --- a/src/engine/SX-book.h +++ b/src/engine/SX-book.h @@ -20,7 +20,10 @@ \********************************************************************/ /** - * @addtogroup Engine_SchedXaction + * @addtogroup Engine + * @{ */ +/** + * @addtogroup SchedXaction * @{ */ /** * @file SX-book.h @@ -57,3 +60,4 @@ AccountGroup * gnc_collection_get_template_group( QofCollection *col ); #endif /* GNC_SX_BOOK_H */ /** @} */ +/** @} */ diff --git a/src/engine/SchedXaction.h b/src/engine/SchedXaction.h index bad8067e5c..1840f845de 100644 --- a/src/engine/SchedXaction.h +++ b/src/engine/SchedXaction.h @@ -18,7 +18,10 @@ * * \********************************************************************/ /** - * @addtogroup Engine_SchedXaction + * @addtogroup Engine + * @{ */ +/** + * @addtogroup SchedXaction * @{ */ /** * @file SchedXaction.h @@ -224,3 +227,4 @@ void xaccSchedXactionSetSlot( SchedXaction *sx, #endif /* XACC_SCHEDXACTION_H */ /** @} */ +/** @} */ diff --git a/src/engine/TransLog.h b/src/engine/TransLog.h index 9b585c6f38..e160cdf628 100644 --- a/src/engine/TransLog.h +++ b/src/engine/TransLog.h @@ -19,14 +19,24 @@ \********************************************************************/ /** @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 */ @@ -69,4 +79,5 @@ void xaccLogSetBaseName (const char *); #endif /* XACC_TRANS_LOG_H */ /** @} */ +/** @} */ diff --git a/src/engine/Transaction.h b/src/engine/Transaction.h index d5555bb5a8..fd22071af2 100644 --- a/src/engine/Transaction.h +++ b/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 @@ -874,3 +876,4 @@ Timespec xaccTransGetVoidTime(const Transaction *tr); #endif /* XACC_TRANSACTION_H */ /** @} */ +/** @} */ diff --git a/src/engine/cap-gains.h b/src/engine/cap-gains.h index 55516ded22..ed2bdbdde5 100644 --- a/src/engine/cap-gains.h +++ b/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 - * + +/** @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 */ #ifndef XACC_CAP_GAINS_H @@ -187,5 +190,6 @@ void xaccLotComputeCapGains (GNCLot *lot, Account *gain_acc); #endif /* XACC_CAP_GAINS_H */ /** @} */ +/** @} */ /* =========================== END OF FILE ======================= */ diff --git a/src/engine/gnc-commodity.h b/src/engine/gnc-commodity.h index 447579a660..d54ac9a07c 100644 --- a/src/engine/gnc-commodity.h +++ b/src/engine/gnc-commodity.h @@ -21,16 +21,23 @@ *******************************************************************/ /** @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 @@ -784,3 +791,4 @@ gboolean gnc_commodity_table_register (void); #endif /* GNC_COMMODITY_H */ /** @} */ +/** @} */ diff --git a/src/engine/gnc-pricedb.h b/src/engine/gnc-pricedb.h index f11189402c..5fa500b1fa 100644 --- a/src/engine/gnc-pricedb.h +++ b/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 - @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 + @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 @@ GNCPrice *gnc_price_create(QofBook *book); 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 @@ void gnc_price_ref(GNCPrice *p); /** 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_source(GNCPrice *p, const char *source); 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 @@ gboolean gnc_price_equal(GNCPrice *p1, GNCPrice *p2); #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 @@ gboolean gnc_price_equal(GNCPrice *p1, GNCPrice *p2); 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 @@ gboolean gnc_price_list_remove(GList **prices, GNCPrice *p); 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 @@ gboolean gnc_price_list_equal(GList *prices1, GList *prices2); 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 @@ void gnc_pricedb_print_contents(GNCPriceDB *db, FILE *f); #define PRICE_VALUE "price-value" /**@}*/ +/** @} */ + #endif /* GNC_PRICEDB_H */ /** @} */ +/** @} */ diff --git a/src/engine/qof.h b/src/engine/qof.h index 61a0420a7f..8a40f7eab3 100644 --- a/src/engine/qof.h +++ b/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"