[Gnucash-changes] Changes to make the documentation display nicely
with Doxygen
Linas Vepstas
linas at cvs.gnucash.org
Fri May 7 00:14:54 EDT 2004
Log Message:
-----------
Changes to make the documentation display nicely with Doxygen
Modified Files:
--------------
gnucash/src/engine:
Account.h
Group.h
Period.h
gnc-engine.h
Revision Data
-------------
Index: Period.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/Period.h,v
retrieving revision 1.18
retrieving revision 1.19
diff -Lsrc/engine/Period.h -Lsrc/engine/Period.h -u -r1.18 -r1.19
--- src/engine/Period.h
+++ src/engine/Period.h
@@ -21,6 +21,8 @@
/** @addtogroup Engine
@{ */
/** @addtogroup Period Accounting Periods
+ The architecture of the Accounting Period design is discussed
+ in greater detail in the file "src/doc/books.txt"
@{ */
/** @file Period.h
* @breif Implement accounting periods, as per design in src/doc/books.txt
Index: Group.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/Group.h,v
retrieving revision 1.71
retrieving revision 1.72
diff -Lsrc/engine/Group.h -Lsrc/engine/Group.h -u -r1.71 -r1.72
--- src/engine/Group.h
+++ src/engine/Group.h
@@ -1,7 +1,5 @@
/********************************************************************\
* Group.h -- chart of accounts (hierarchical tree of accounts) *
- * Copyright (C) 1997 Robin D. Clark *
- * Copyright (C) 1997-2000,2003 Linas Vepstas <linas at linas.org> *
* *
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
@@ -21,6 +19,18 @@
* Boston, MA 02111-1307, USA gnu at gnu.org *
* *
\********************************************************************/
+/** @addtogroup Engine
+ @{ */
+/** @addtogroup AccountGroup
+ Accounts are organized into a heirarchical tree. The account
+ group is the parent node that holds accounts.
+ @{ */
+/** @file Group.h
+ @brief Account handling public routines
+ @author Copyright (C) 1997 Robin D. Clark
+ @author Copyright (C) 1997-2000,2003 Linas Vepstas <linas at linas.org>
+*/
+
#ifndef XACC_ACCOUNT_GROUP_H
#define XACC_ACCOUNT_GROUP_H
@@ -34,79 +44,104 @@
/** PROTOTYPES ******************************************************/
-/*
+/** @name Constructors, Destructors */
+/** @{ */
+/**
* The xaccMallocAccountGroup() routine will create a new account group.
* This is an internal-use function, you almost certainly want to
* be using the xaccGetAccountGroup() routine instead.
*/
AccountGroup *xaccMallocAccountGroup (QofBook *book);
-/*
+/**
* The xaccGetAccountGroup() routine will return the top-most
* account group associated with the indicated book.
*/
AccountGroup * xaccGetAccountGroup (QofBook *book);
+
+/** huh ?? */
AccountGroup * xaccCollGetAccountGroup (QofCollection *col);
-/*
- * The xaccAccountDestroy() routine will destroy and free all
+/** The xaccAccountDestroy() routine will destroy and free all
* the data associated with this account group. The group
* must have been opened for editing with
* xaccAccountGroupBeginEdit() first, before the Destroy is called.
*/
void xaccAccountGroupDestroy (AccountGroup *grp);
-
-/* XXX backwards-compat define, remove at later convenience */
+/* @deprecated XXX backwards-compat define, remove at later convenience */
#define gnc_book_get_group xaccGetAccountGroup
+/** Return the book to which this account belongs */
QofBook * xaccGroupGetBook (AccountGroup *group);
+/** DOCUMENT ME! */
+gboolean xaccGroupEqual(AccountGroup *a, AccountGroup *b,
+ gboolean check_guids);
+
+/** @} */
+
+/** @name Editing */
+/** @{ */
+/** Start of begine/commit sequence. All changes to an account
+ * group should be bracketed by calls to begin-edit/commit-edit
+ */
void xaccAccountGroupBeginEdit (AccountGroup *grp);
+
+/** End of begine/commit sequence. All changes to an account
+ * group should be bracketed by calls to begin-edit/commit-edit
+ */
void xaccAccountGroupCommitEdit (AccountGroup *grp);
-/*
+/** The xaccGroupNotSaved() subroutine will return TRUE
+ * if any account in the group or in any subgroup
+ * hasn't been saved.
+ XXX this should be moved to private header file, this is not a public routine!
+ */
+gboolean xaccGroupNotSaved (AccountGroup *grp);
+
+/** The xaccGroupMarkSaved() subroutine will mark
+ * the entire group as having been saved, including
+ * all of the child accounts.
+
+ XXX this should be moved to private header file, this is not a public routine!
+ */
+void xaccGroupMarkSaved (AccountGroup *grp);
+
+/** The xaccGroupMarkNotSaved() subroutine will mark
+ * the given group as not having been saved.
+ XXX this should be moved to private header file, this is not a public routine!
+ */
+void xaccGroupMarkNotSaved (AccountGroup *grp);
+/** @} */
+
+/** @name Concatenation, Merging */
+/** @{ */
+/**
* The xaccGroupConcatGroup() subroutine will move (reparent)
* all accounts from the "src" group to the "dest" group,
* preserving the account heirarchy. It will also take care
* that the moved accounts will have the "dest" group's book
* parent as well.
- *
- * The xaccGroupCopyGroup() subroutine will copy all accounts
+ */
+void xaccGroupConcatGroup (AccountGroup *dest, AccountGroup *src);
+
+/** The xaccGroupCopyGroup() subroutine will copy all accounts
* from the "src" group to the "dest" group, preserving the
* account heirarchy. It will also take care that the moved
* accounts will have the "dest" group's book parent as well.
* This routine will *NOT* copy any splits/transactions.
* It will copy the KVP trees in each account.
- *
- * The xaccGroupMergeAccounts() subroutine will go through a group,
- * merging all accounts that have the same name and description.
- * This function is useful when importing Quicken(TM) files.
*/
-
-void xaccGroupConcatGroup (AccountGroup *dest, AccountGroup *src);
void xaccGroupCopyGroup (AccountGroup *dest, AccountGroup *src);
-void xaccGroupMergeAccounts (AccountGroup *grp);
-/*
- * The xaccGroupNotSaved() subroutine will return TRUE
- * if any account in the group or in any subgroup
- * hasn't been saved.
- *
- * The xaccGroupMarkSaved() subroutine will mark
- * the entire group as having been saved, including
- * all of the child accounts.
- *
- * The xaccGroupMarkNotSaved() subroutine will mark
- * the given group as not having been saved.
+/** The xaccGroupMergeAccounts() subroutine will go through a group,
+ * merging all accounts that have the same name and description.
+ * This function is useful when importing Quicken(TM) files.
*/
+void xaccGroupMergeAccounts (AccountGroup *grp);
-gboolean xaccGroupNotSaved (AccountGroup *grp);
-void xaccGroupMarkSaved (AccountGroup *grp);
-void xaccGroupMarkNotSaved (AccountGroup *grp);
-
-/*
- * The xaccGroupInsertAccount() subroutine will insert the indicated
+/** The xaccGroupInsertAccount() subroutine will insert the indicated
* account into the indicated group. If it already is the child
* of another group, it will be removed there first. If the
* account belongs to a different book than the the group, it
@@ -114,100 +149,118 @@
* entity tables, generating destroy & create events). If the
* account is removed from and inserted into the same group, the
* overall account sort order will be recomputed.
- *
- * The xaccAccountInsertSubAccount() does the same, except that
- * the parent is specified as an account.
*/
-
void xaccGroupInsertAccount (AccountGroup *grp, Account *acc);
+
+/** The xaccAccountInsertSubAccount() does the same, except that
+ * the parent is specified as an account.
+ */
void xaccAccountInsertSubAccount (Account *parent, Account *child);
+/** @} */
-/*
- * The xaccGroupGetNumSubAccounts() subroutine returns the number
+/** @name Counting the Size and Depth of the Account Tree */
+/** @{ */
+/** The xaccGroupGetNumSubAccounts() subroutine returns the number
* of accounts, including subaccounts, in the account group
- *
- * The xaccGroupGetNumAccounts() subroutine returns the number
+ */
+int xaccGroupGetNumSubAccounts (AccountGroup *grp);
+
+/** The xaccGroupGetNumAccounts() subroutine returns the number
* of accounts in the indicated group only (children not counted).
- *
- * The xaccGroupGetDepth() subroutine returns the length of the
+ */
+int xaccGroupGetNumAccounts (AccountGroup *grp);
+
+/** The xaccGroupGetDepth() subroutine returns the length of the
* longest tree branch. Each link between an account and its
* (non-null) children counts as one unit of length.
*/
-
-int xaccGroupGetNumSubAccounts (AccountGroup *grp);
-int xaccGroupGetNumAccounts (AccountGroup *grp);
int xaccGroupGetDepth (AccountGroup *grp);
+/** @} */
+
+/** @name Getting Accounts and Subaccounts */
+/** @{ */
+/** DOCUMENT ME! is this routine deprecated? XXX using index is weird! */
Account * xaccGroupGetAccount (AccountGroup *group, int index);
-/*
- * The xaccGroupGetSubAccounts() subroutine returns an list of the accounts,
+/** The xaccGroupGetSubAccounts() subroutine returns an list of the accounts,
* including subaccounts, in the account group. The returned list
* should be freed with g_list_free() when no longer needed.
- *
- * The xaccGroupGetAccountList() subroutines returns only the immediate
+ */
+AccountList * xaccGroupGetSubAccounts (AccountGroup *grp);
+
+/** The xaccGroupGetAccountList() subroutines returns only the immediate
* children of the account group. The returned list should *not*
* be freed by the caller.
*/
-
-AccountList * xaccGroupGetSubAccounts (AccountGroup *grp);
AccountList * xaccGroupGetAccountList (AccountGroup *grp);
-/*
- * The xaccGetAccountFromName() subroutine fetches the
+/** The xaccGroupGetRoot() subroutine will find the topmost
+ * (root) group to which this group belongs.
+ */
+AccountGroup * xaccGroupGetRoot (AccountGroup *grp);
+
+/** The xaccGetAccountRoot() subroutine will find the topmost
+ * (root) group to which this account belongs.
+ */
+AccountGroup * xaccAccountGetRoot (Account *account);
+
+/** The xaccGroupGetParentAccount() subroutine returns the parent
+ * account of the group, or NULL.
+ */
+Account * xaccGroupGetParentAccount (AccountGroup *group);
+
+/** @} */
+
+/** @name Getting Accounts and Subaccounts by Name */
+/** @{ */
+/** The xaccGetAccountFromName() subroutine fetches the
* account by name from the collection of accounts
* in the indicated AccountGroup group. It returns NULL if the
* account was not found.
- *
- * The xaccGetAccountFromFullName() subroutine works like
+ */
+Account *xaccGetAccountFromName (AccountGroup *group, const char *name);
+
+/** The xaccGetAccountFromFullName() subroutine works like
* xaccGetAccountFromName, but uses fully-qualified names
* using the given separator.
- *
- * The xaccGetPeerAccountFromName() subroutine fetches the
+ */
+Account *xaccGetAccountFromFullName (AccountGroup *group,
+ const char *name,
+ const char separator);
+
+/** The xaccGetPeerAccountFromName() subroutine fetches the
* account by name from the collection of accounts
* in the same AccountGroup anchor group. It returns NULL if the
* account was not found.
- *
- * The xaccGetPeerAccountFromFullName() subroutine works like
+ */
+Account *xaccGetPeerAccountFromName (Account *account, const char *name);
+
+/** The xaccGetPeerAccountFromFullName() subroutine works like
* xaccGetPeerAccountFromName, but uses fully-qualified
* names using the given separator.
*/
-
-Account *xaccGetAccountFromName (AccountGroup *group, const char *name);
-Account *xaccGetAccountFromFullName (AccountGroup *group,
- const char *name,
- const char separator);
-Account *xaccGetPeerAccountFromName (Account *account, const char *name);
Account *xaccGetPeerAccountFromFullName (Account *acc,
const char * name,
const char separator);
-/*
- * The xaccGroupGetRoot() subroutine will find the topmost
- * (root) group to which this group belongs.
- *
- * The xaccGetAccountRoot() subroutine will find the topmost
- * (root) group to which this account belongs.
- */
-AccountGroup * xaccGroupGetRoot (AccountGroup *grp);
-AccountGroup * xaccAccountGetRoot (Account *account);
+/** @} */
-/* The xaccGroupGetParentAccount() subroutine returns the parent
- * account of the group, or NULL.
- */
-Account * xaccGroupGetParentAccount (AccountGroup *group);
+/** @name Traversal, ForEach */
+/** @{ */
-/* The xaccGroupMapAccounts() routine will traverse the account
+typedef gpointer (*AccountCallback)(Account *a, gpointer data);
+
+/** The xaccGroupMapAccounts() routine will traverse the account
group, returning a list of accounts. If the callback
returns null for a given item, it won't show up in
the result list. You should free the returned list when
you are done with it.
*/
-typedef gpointer (*AccountCallback)(Account *a, gpointer data);
AccountList *xaccGroupMapAccounts(AccountGroup *grp,
AccountCallback,
gpointer data);
-/* The xaccGroupForEachAccount() method will traverse the AccountGroup
+/** The xaccGroupForEachAccount() method will traverse the AccountGroup
* tree, calling 'func' on each account. Traversal will stop when
* func returns a non-null value, and the routine wil return with that
* value. If 'deeply' is FALSE, then only the immediate children of
@@ -220,10 +273,9 @@
gpointer data,
gboolean deeply);
-gboolean xaccGroupEqual(AccountGroup *a, AccountGroup *b,
- gboolean check_guids);
+/** @} */
-/*
+/** @name Staged Traversal
* The following functions provide support for "staged traversals"
* over all of the transactions in an account or group. The idea
* is to be able to perform a sequence of traversals ("stages"),
@@ -259,37 +311,38 @@
* can be changed by enlarging "marker" in the transaction struct.
* */
-/* xaccGroupBeginStagedTransactionTraversals() resets the traversal
+/** @{ */
+/** xaccGroupBeginStagedTransactionTraversals() resets the traversal
* marker inside each of all the transactions in the group so that
* a new sequence of staged traversals can begin.
- *
- * xaccSplitsBeginStagedTransactionTraversals() resets the traversal
+ */
+void xaccGroupBeginStagedTransactionTraversals(AccountGroup *grp);
+
+/** xaccSplitsBeginStagedTransactionTraversals() resets the traversal
* marker for each transaction which is a parent of one of the
* splits in the list.
- *
- * xaccAccountBeginStagedTransactionTraversals() resets the traversal
+ */
+void xaccSplitsBeginStagedTransactionTraversals(SplitList *splits);
+
+/** xaccAccountBeginStagedTransactionTraversals() resets the traversal
* marker for each transaction which is a parent of one of the
* splits in the account.
- *
*/
-
-void xaccGroupBeginStagedTransactionTraversals(AccountGroup *grp);
-void xaccSplitsBeginStagedTransactionTraversals(SplitList *splits);
void xaccAccountBeginStagedTransactionTraversals(Account *account);
-/* xaccTransactionTraverse() checks the stage of the given transaction.
+/** xaccTransactionTraverse() checks the stage of the given transaction.
* If the transaction hasn't reached the given stage, the transaction
* is updated to that stage and the function returns TRUE. Otherwise
* no change is made and the function returns FALSE.
- *
- * xaccSplitTransactionTraverse() behaves as above using the parent of
- * the given split.
*/
-
gboolean xaccTransactionTraverse(Transaction *trans, int stage);
+
+/** xaccSplitTransactionTraverse() behaves as above using the parent of
+ * the given split.
+ */
gboolean xaccSplitTransactionTraverse(Split *split, int stage);
-/* xaccGroupStagedTransactionTraversal() calls thunk on each
+/** xaccGroupStagedTransactionTraversal() calls thunk on each
* transaction in the group whose current marker is less than the
* given `stage' and updates each transaction's marker to be `stage'.
* The traversal will stop if thunk() returns a non-zero value.
@@ -306,7 +359,7 @@
TransactionCallback,
void *data);
-/* xaccAccountStagedTransactionTraversal() calls thunk on each
+/** xaccAccountStagedTransactionTraversal() calls thunk on each
* transaction in the account whose current marker is less than the
* given `stage' and updates each transaction's marker to be `stage'.
* The traversal will stop if thunk() returns a non-zero value.
@@ -353,4 +406,8 @@
int xaccGroupForEachTransaction(AccountGroup *g,
TransactionCallback, void *data);
+/** @} */
#endif /* XACC_ACCOUNT_GROUP_H */
+/** @} */
+/** @} */
+
Index: gnc-engine.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/gnc-engine.h,v
retrieving revision 1.28
retrieving revision 1.29
diff -Lsrc/engine/gnc-engine.h -Lsrc/engine/gnc-engine.h -u -r1.28 -r1.29
--- src/engine/gnc-engine.h
+++ src/engine/gnc-engine.h
@@ -19,7 +19,11 @@
* Boston, MA 02111-1307, USA gnu at gnu.org *
* *
********************************************************************/
-/** @addtogroup Engine
+/** @addtogroup Engine GnuCash Engine: Core, Non-GUI Accounting Functions
+ The GnuCash Engine provides a set of objects and classes that
+ encapsulate typical financial accounting concepts. The GnuCash
+ GUI is expected to manipulate these objects through the provided
+ engine API.
@{ */
/** @file gnc-engine.h
@brief All type declarations for the whole Gnucash engine
@@ -35,13 +39,13 @@
#include <glib.h>
#include "qofid.h"
-/* IDENTIFIERS *****************************************************/
-/** GUID Identifiers can be used to reference Accounts, Transactions,
+/** @brief IDENTIFIERS
+ * GUID Identifiers can be used to reference Accounts, Transactions,
* Splits and other objects. These Gnucash types are referred to as Gnucash
* entities. GUID 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 are 'typed' with strings. The ids used in gnucash are
* defined below. An id with type GNC_ID_NONE does not refer to any
* entity, although that may change as new ids are created. An id with
@@ -75,7 +79,6 @@
/* TYPES **********************************************************/
/** @brief Account in Gnucash.
- *
* This is the typename for an account. The actual structure is
* defined in the private header AccountP.h, but no one outside the
* engine should include that file. Instead, access that data only
@@ -87,7 +90,6 @@
typedef struct account_group_s AccountGroup;
/** @brief Split in Gnucash.
- *
* A "split" is more commonly refered to as a "entry" in a
* "transaction". Each split belongs to one Account and one
* Transaction. The split is one out of several parts a Transaction is
@@ -100,7 +102,6 @@
typedef struct split_s Split;
/** @brief Transaction in Gnucash.
- *
* A Transaction is a piece of business done; the transfer of money
* from one account to one or more other accounts. Each Transaction is
* divided into one or more Splits (usually two).
@@ -112,7 +113,6 @@
typedef struct transaction_s Transaction;
/** @brief An article that is bought and sold.
- *
* A Commodity is the most general term of what an account keeps track
* of. Usually this is a monetary currency, but it can also be a stock
* share or even a precious metal. Every account keeps track of
@@ -132,7 +132,6 @@
typedef struct gnc_commodity_table_s gnc_commodity_table;
/** @breif Identifies that something sold at one time was bought at another.
- *
* A GNCLot provides a way of tracking physical items as they are
* bought and sold in different transactions. By identifying
* the individual, underlying physical objects, it provides the
@@ -144,7 +143,6 @@
typedef struct gnc_lot_struct GNCLot;
/** @breif Price of commodity on a given date.
- *
* A GNCPrice encapsulates price information: the cost of a commodity
* expressed as a currency, on a given date. It also holds info about
* the provenance of the price: where it came from, its general validity.
Index: Account.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/Account.h,v
retrieving revision 1.135
retrieving revision 1.136
diff -Lsrc/engine/Account.h -Lsrc/engine/Account.h -u -r1.135 -r1.136
--- src/engine/Account.h
+++ src/engine/Account.h
@@ -165,7 +165,7 @@
/** @name Account lookup and GUID routines */
/** @{ */
-/** deprecated */
+/** @deprecated */
#define xaccAccountGetBook(X) qof_instance_get_book(QOF_INSTANCE(X))
#define xaccAccountGetGUID(X) qof_entity_get_guid(QOF_ENTITY(X))
#define xaccAccountReturnGUID(X) (X ? *(qof_entity_get_guid(QOF_ENTITY(X))) : *(guid_null()))
@@ -252,7 +252,7 @@
void xaccAccountSetAutoInterestXfer (Account *account, gboolean value);
/** @} */
-/* @name Account Commodity setters/getters
+/** @name Account Commodity setters/getters
* Accounts are used to store an amount of 'something', that 'something'
* is called the 'commodity'. An account can only hold one kind of
* commodity. The following are used to get and set the commodity,
@@ -285,13 +285,13 @@
/** Set the account's commodity */
void xaccAccountSetCommodity (Account *account, gnc_commodity *comm);
-/* deprecated do not use */
+/** @deprecated do not use */
#define DxaccAccountSetSecurity xaccAccountSetCommodity
/** Get the account's commodity */
gnc_commodity * xaccAccountGetCommodity (Account *account);
-/* deprecated do not use */
+/** @deprecated do not use */
#define DxaccAccountGetSecurity xaccAccountGetCommodity
/** Return the SCU for the account. If a non-standard SCU has been
@@ -310,7 +310,7 @@
*/
void xaccAccountSetCommoditySCU (Account *account, int frac);
-/* deprecated -- do not use for future development */
+/** @deprecated -- do not use for future development */
#define xaccAccountSetCommoditySCUandFlag xaccAccountSetCommoditySCU
/** Set the flag indicating that this account uses a non-standard SCU. */
@@ -676,7 +676,7 @@
/*@}*/
-/** @name Account deprecated routines. */
+/** @name Deprecated Routines. */
/** @{ */
/** @deprecated The current API associates only one thing with an
More information about the Gnucash-changes
mailing list