diff --git a/src/doc/doxygen_main_page.c b/src/doc/doxygen_main_page.c
index 31754f7283..2d2c3405d9 100644
--- a/src/doc/doxygen_main_page.c
+++ b/src/doc/doxygen_main_page.c
@@ -15,6 +15,42 @@ of the files "by the book". Until then, feel free to start
documenting or playing with doxygen configuration. This main page can
be found in src/doc/doxygen_main_page.c .
+\subsection style_discussion Style discussion
+
+[cstim 2003-03-25] It's too bad that doxygen doesn't show the "Member
+Groups" (those created on-the-fly with @{ and @}) inside the Module
+pages (named groups, created with \\addtogroup). This means that the
+"member group" grouping of the account-related functions is only shown
+in the documentation of the Account.h header file. But in the
+documentation of the Engine group (module) all these functions are
+lumped together into one unreadable long list. This is bad (because
+1. nobody will read through the long list, 2. hyperlinks don't even
+work properly since the document is simply too big). Isn't there a way
+to have this member groups also show up on the module pages...?
+Unfortunately nesting several named modules (groups) into one another
+doesn't really solve this problem, because that way all
+account-related functions will show up in one separate group each --
+which makes these unreadable as well. Maybe it would even be better to
+not have these function names show up on the module page at all. If
+they appear *only* on the file page, they will show up in their
+respective "member group" grouping and everything would be fine.
+
+[cstim 2003-03-25] The "Data Structures" page of doxygen doesn't show
+anything useful for gnucash. Obviously doxygen only accepts "real" C
+struct definitions for inclusion on that page. However, all gnucash
+data structures are defined somewhere in private headers, and only the
+typedefs are publically visible. Isn't there a way to have doxygen
+show the documentation for the typedefs on the "Data
+Structures" page? Unfortunately I don't know how.
+
+[cstim 2003-03-25] This mainpage file should at some time be moved to
+a file name ending in .txt or even .html. It's a PITA to edit one huge
+C comment. All text editors will run amok sooner or later (well,
+XEmacs does :) and will not support proper HTML markup and editing
+inside this C comment... well, that's not really a problem of the
+outcome, yes. It would just make life easier for editing this
+non-source file.
+
\subsection config Editing Doxygen configuration
To edit the doxygen configuration, you can use:
@@ -25,11 +61,18 @@ doxywizard doxygen.cfg &
\subsection reference Doxygen reference documentation
-The Doxygen web site (http://www.stack.nl/~dimitri/doxygen/) has a complete user manual. For the impatient, here are the most interesting sections:
-- How to write documentation blocks for files, functions, variables, etc.: http://www.stack.nl/~dimitri/doxygen/docblocks.html.
- Do not forget to add a file documentation block (@file) at the top of your file,
-otherwise, your documentation will not appear in the html.
-- List of the special commands you can use within your documentation blocks: http://www.stack.nl/~dimitri/doxygen/commands.html
+The Doxygen web site (http://www.stack.nl/~dimitri/doxygen/) has a
+complete user manual. For the impatient, here are the most
+interesting sections:
+
+- How to write grouped documentation for files, functions, variables,
+etc.: http://www.stack.nl/~dimitri/doxygen/grouping.html . Do not
+forget to add a file documentation block (@file) at the top of your
+file. Otherwise, all documentation in that file will not appear
+in the html output.
+
+- List of the special commands you can use within your documentation
+blocks: http://www.stack.nl/~dimitri/doxygen/commands.html
\section contact Contacts
diff --git a/src/engine/Account.h b/src/engine/Account.h
index 405fc82d91..d6303ba51d 100644
--- a/src/engine/Account.h
+++ b/src/engine/Account.h
@@ -47,7 +47,7 @@
typedef enum
{
- BAD_TYPE = -1,
+ BAD_TYPE = -1, /**< Not a type */
NO_TYPE = -1,/**< Not a type */
BANK = 0, /**< The bank account type denotes a savings or checking account
@@ -64,11 +64,15 @@ typedef enum
* which show three columns: price, number of shares, and value. */
MUTUAL= 6, /**< Mutual Fund accounts will typically be shown in registers
* which show three columns: price, number of shares, and value. */
- CURRENCY = 7, /**< The currency account type indicates that the account is a
- * currency trading account. In many ways, a currency trading
- * account is like a stock trading account, where both values
- * and share quantities are set.
- * @note: DEPRECATED?*/
+ CURRENCY = 7, /**< The currency account type indicates that the
+ * account is a currency trading account. In many
+ * ways, a currency trading account is like a stock
+ * trading account. It is shown in the register with
+ * three columns: price, number of shares, and
+ * value. Note: Since version 1.7.0, this account is
+ * no longer needed to exchange currencies between
+ * accounts, so this type will probably become
+ * deprecated sometime in the future. */
INCOME = 8, /**< Income accounts are used to denote income */
EXPENSE = 9,/**< Expense accounts are used to denote expenses. */
@@ -83,38 +87,15 @@ typedef enum
* just aren't ready for prime time */
/* bank account types */
- CHECKING = 13,
- SAVINGS = 14,
- MONEYMRKT = 15,
- CREDITLINE = 16, /**< line of credit */
+ CHECKING = 13, /**< bank account type -- don't use this for now, see NUM_ACCOUNT_TYPES */
+ SAVINGS = 14, /**< bank account type -- don't use this for now, see NUM_ACCOUNT_TYPES */
+ MONEYMRKT = 15, /**< bank account type -- don't use this for now, see NUM_ACCOUNT_TYPES */
+ CREDITLINE = 16, /**< line of credit -- don't use this for now, see NUM_ACCOUNT_TYPES */
} GNCAccountType;
-/** The xaccAccountGetTypeStr() routine returns a string suitable for
- * use in the GUI/Interface. These strings should be translated
- * to the local language. */
-const char * xaccAccountGetTypeStr (GNCAccountType type);
-GNCAccountType xaccAccountGetTypeFromStr (const gchar *str);
-/** @name Account Conversion routines
- * Conversion routines for the account types to/from strings
- * that are used in persistant storage, communications. These
- * strings should *not& be translated to the local language.
- * Typical converstion is INCOME -> "INCOME". */
-/** @{ */
-char * xaccAccountTypeEnumAsString (GNCAccountType type);
-gboolean xaccAccountStringToType (const char* str, GNCAccountType *type);
-GNCAccountType xaccAccountStringToEnum (const char* str);
-/** @} */
-
-/** Return TRUE if accounts of type parent_type can have accounts
- * of type child_type as children. */
-gboolean xaccAccountTypesCompatible (GNCAccountType parent_type,
- GNCAccountType child_type);
-
-/* PROTOTYPES ******************************************************/
-
-/** @name Account Constructors/Destructors and Edit/Commit */
+/** @name Account Constructors, Edit/Commit, Comparison */
/** @{ */
/** Constructor */
@@ -146,18 +127,24 @@ void xaccAccountCommitEdit (Account *account);
* (by calling xaccAccountBeginEdit()) before calling this routine.*/
void xaccAccountDestroy (Account *account);
+/** Compare two accounts for equality - this is a deep compare. */
+gboolean xaccAccountEqual(Account *a, Account* b, gboolean check_guids);
+
+/** The xaccAccountOrder() subroutine defines a sorting order
+ * on accounts. It takes pointers to two accounts, and
+ * returns -1 if the first account is "less than" the second,
+ * returns +1 if the first is "greater than" the second, and
+ * 0 if they are equal. To determine the sort order, first
+ * the account codes are compared, and if these are equal, then
+ * account types, and, if these are equal, the account names.
+ */
+int xaccAccountOrder (Account **account_1, Account **account_2);
+
/** @} */
-/** @name Account kvp_frame getters/setters */
-/** @{ */
-kvp_frame * xaccAccountGetSlots (Account *account);
-void xaccAccountSetSlots_nc(Account *account, kvp_frame *frame);
-/** @} */
+/* ------------------ */
-/** @return The book where the account is stored */
-GNCBook * xaccAccountGetBook (Account *account);
-
-/** @name Account GUID subroutines */
+/** @name Account lookup and GUID routines */
/** @{ */
/** The xaccAccountGetGUID() subroutine will return the
@@ -175,64 +162,31 @@ Account * xaccAccountLookup (const GUID *guid, GNCBook *book);
/** xaccAccountLookupDirect performs the same function as
* xaccAccountLookup but takes a GUID struct directly. */
Account * xaccAccountLookupDirect (GUID guid, GNCBook *book);
+
+/** The xaccAccountLookupTwin() routine will find the "twin" of this
+ * account 'acc' in the given other 'book' (if the twin exists).
+ *
+ * When accounts are copied or cloned, both of the pair are marked
+ * with the guid of thier copy, thus allowing the sibling-copy of
+ * an account to be found. Since the sibling may end up in a
+ * different book, we need a way of finding it, given only that we
+ * know the book, and that we know its twin.
+ *
+ * That's what this routine does. Given some book 'book', and an
+ * account 'acc', it will find the sibling account of 'acc' that is
+ * in 'book', and return it. If not found, it returns NULL. This
+ * routine uses the 'gemini' kvp values to do its work. */
+Account * xaccAccountLookupTwin (Account *acc, GNCBook *book);
/** @} */
-/** The xaccAccountLookupTwin() routine will find the
- * "twin" of this account (if it exists) in another book.
- * When accounts are copied or cloned, both of the pair
- * are marked with the guid of thier copy, thus allowing
- * the sibling-copy of an account to be found. Since the
- * sibling may end up in a different book, we need a way
- * of finding it, given only that we know the book, and
- * that we know its twin. That's what this routine does.
- * Given some book 'book', and an account 'acc', it will
- * find the sibling account of 'acc' that is in 'book',
- * and return it. If not found, it returns NULL.
- * This routine uses the 'gemini' kvp values to do its work. */
-Account * xaccAccountLookupTwin (Account *acc, GNCBook *book);
-
/* ------------------ */
-/** Compare two accounts for equality - this is a deep compare. */
-gboolean xaccAccountEqual(Account *a, Account* b, gboolean check_guids);
-
-/* ------------------ */
-/** The xaccAccountInsertLot() method will register the indicated lot
- * with this account. Any splits later inserted into this lot must
- * belong to this account. If the lot is already in another account,
- * the lot, and all of the splits in it, will be moved from that
- * account to this account. */
-void xaccAccountInsertLot (Account *, GNCLot *);
-void xaccAccountRemoveLot (Account *, GNCLot *);
-
-/** The xaccAccountInsertSplit() method will insert the indicated
- * split into the indicated account. If the split already
- * belongs to another account, it will be removed from that
- * account first.*/
-void xaccAccountInsertSplit (Account *account, Split *split);
-
-/** The xaccAccountFixSplitDateOrder() subroutine checks to see if
- * a split is in proper sorted date order with respect
- * to the other splits in this account. */
-void xaccAccountFixSplitDateOrder (Account *account, Split *split);
-
-/** The xaccTransFixSplitDateOrder() checks to see if
- * all of the splits in this transaction are in
- * proper date order. */
-void xaccTransFixSplitDateOrder (Transaction *trans);
-
-/** The xaccAccountOrder() subroutine defines a sorting order
- * on accounts. It takes pointers to two accounts, and
- * returns -1 if the first account is "less than" the second,
- * returns +1 if the first is "greater than" the second, and
- * 0 if they are equal. To determine the sort order, first
- * the account codes are compared, and if these are equal, then
- * account types, and, if these are equal, the account names.
- */
-int xaccAccountOrder (Account **account_1, Account **account_2);
-
/** @name Account general setters/getters */
/** @{ */
+
+/** @return The book where the account is stored */
+GNCBook * xaccAccountGetBook (Account *account);
+
/** Set the account's type */
void xaccAccountSetType (Account *account, GNCAccountType);
/** Set the account's name */
@@ -258,6 +212,43 @@ const char * xaccAccountGetDescription (Account *account);
const char * xaccAccountGetNotes (Account *account);
/** Get the last num field of an Account */
const char * xaccAccountGetLastNum (Account *account);
+
+/** The xaccAccountGetFullName routine returns the fully qualified name
+ * of the account using the given separator char. The name must be
+ * g_free'd after use. The fully qualified name of an account is the
+ * concatenation of the names of the account and all its ancestor
+ * accounts starting with the topmost account and ending with the
+ * given account. Each name is separated by the given character.
+ *
+ * @note: WAKE UP!
+ * Unlike all other gets, the string returned by xaccAccountGetFullName()
+ * must be freed by you the user !!!
+ * hack alert -- since it breaks the rule of string allocation, maybe this
+ * routine should not be in this library, but some utility library?
+ */
+char * xaccAccountGetFullName (Account *account, const char separator);
+
+/** The xaccAccountSetPriceSrc() and xaccAccountGetPriceSrc() routines
+ are used to get and set a string that identifies the Finance::Quote
+ backend that should be used to retrieve online prices. See
+ price-quotes.scm for more information.*/
+void xaccAccountSetPriceSrc (Account *account, const char *src);
+/** The xaccAccountSetPriceSrc() and xaccAccountGetPriceSrc() routines
+ are used to get and set a string that identifies the Finance::Quote
+ backend that should be used to retrieve online prices. See
+ price-quotes.scm for more information.*/
+const char * xaccAccountGetPriceSrc (Account *account);
+
+/** Returns a per-account flag: Prior to reconciling an account which
+ charges or pays interest, this flag tells whether to prompt the
+ user to enter a transaction for the interest charge or
+ payment. This per-account flag overrides the global preference. */
+gboolean xaccAccountGetAutoInterestXfer (Account *account, gboolean default_value);
+/** Sets a per-account flag: Prior to reconciling an account which
+ charges or pays interest, this flag tells whether to prompt the
+ user to enter a transaction for the interest charge or
+ payment. This per-account flag overrides the global preference. */
+void xaccAccountSetAutoInterestXfer (Account *account, gboolean value);
/** @} */
/* @name Account Commodity setters/getters
@@ -280,7 +271,22 @@ const char * xaccAccountGetLastNum (Account *account);
/** Set the account's commodity */
void xaccAccountSetCommodity (Account *account, gnc_commodity *comm);
-/** Get the account's commodity */
+/** Get the account's commodity
+ *
+ * This is from the new commodity access routines.
+ *
+ * The account structure no longer stores two commodities ('currency'
+ * and 'security'). Instead it stores only one commodity. This single
+ * commodity is the one formerly known as 'security'. Use
+ * xaccAccountSetCommodity() and xaccAccountGetCommodity() to set and
+ * fetch it. (This transition has been done between version 1.6.x and
+ * 1.7.0.)
+ *
+ * Basically, the engine eliminates the 'currency' field of the
+ * Account structure. Instead, the common currency is stored with the
+ * transaction. The 'value' of a split is a translation of the
+ * Split's 'amount' (which is the amount of the Account's commodity
+ * involved) into the Transaction's balancing currency. */
gnc_commodity * xaccAccountGetCommodity (Account *account);
/** DOCUMENT ME! */
int xaccAccountGetCommoditySCU (Account *account);
@@ -296,6 +302,9 @@ void xaccAccountSetNonStdSCU (Account *account, gboolean flag);
gboolean xaccAccountGetNonStdSCU (Account *account);
/**@}*/
+
+/** @name Account Balance */
+/*@{*/
/** Get the current balance of the account */
gnc_numeric xaccAccountGetBalance (Account *account);
/** Get the current balance of the account, only including cleared transactions */
@@ -304,46 +313,23 @@ gnc_numeric xaccAccountGetClearedBalance (Account *account);
gnc_numeric xaccAccountGetReconciledBalance (Account *account);
/** Get the balance of the account as of the date specified */
gnc_numeric xaccAccountGetBalanceAsOfDate (Account *account, time_t date);
+/*@}*/
-/** @name Account Deprecated currency/security access routines.
- *
- * @deprecated The current API associates only one thing with an account:
- * the 'commodity'. Use xaccAccountGetCommodity() to fetch it.*/
-/** @{ */
-
-/** @deprecated Don't use doubles anymore, only use gnc_numerics.
- these two funcs take control of their gnc_commodity args. Don't free */
-void DxaccAccountSetCurrency (Account *account, gnc_commodity *currency,
- GNCBook *book);
-/** @deprecated Don't use doubles anymore, only use gnc_numerics.
- these two funcs take control of their gnc_commodity args. Don't free */
-void DxaccAccountSetSecurity (Account *account, gnc_commodity *security,
- GNCBook *book);
-/** @deprecated Don't use doubles anymore, only use gnc_numerics.*/
-gnc_commodity * DxaccAccountGetCurrency (Account *account,
- GNCBook *book);
-/** @deprecated Don't use doubles anymore, only use gnc_numerics. */
-gnc_commodity * DxaccAccountGetSecurity (Account *account,
- GNCBook *book);
-/** @deprecated Don't use doubles anymore, only use gnc_numerics. */
-void DxaccAccountSetCurrencySCU (Account *account, int frac);
-/** @deprecated Don't use doubles anymore, only use gnc_numerics. */
-int DxaccAccountGetCurrencySCU (Account *account);
-/**@}*/
-
-/** Delete any old data in the account's kvp data.
- * This includes the old currency and security fields. */
-void xaccAccountDeleteOldData (Account *account);
-
-/** @name Account Children and Parent getters/setters */
+/** @name Account Children and Parent */
/** @{ */
/** DOCUMENT ME! */
AccountGroup * xaccAccountGetChildren (Account *account);
-/** DOCUMENT ME! */
+/** DOCUMENT ME!
+ *
+ * FIXME: Is the ancestor account xaccAccountHasAncestor() the same as the parent account?
+ */
AccountGroup * xaccAccountGetParent (Account *account);
-/** DOCUMENT ME! */
+/** DOCUMENT ME!
+ *
+ * FIXME: Is the ancestor account xaccAccountHasAncestor() the same as the parent account?
+ */
Account * xaccAccountGetParentAccount (Account *account);
/** DOCUMENT ME! */
GList * xaccAccountGetDescendants (Account *account);
@@ -352,8 +338,82 @@ GList * xaccAccountGetDescendants (Account *account);
void xaccAccountSetReconcileChildrenStatus(Account *account, gboolean status);
/** DOCUMENT ME! */
gboolean xaccAccountGetReconcileChildrenStatus(Account *account);
+/** Returns true if the account has 'ancestor' as an ancestor.
+ * Returns false if either one is NULL.
+ *
+ * FIXME: Is the ancestor account the same as the parent account? */
+gboolean xaccAccountHasAncestor (Account *account, Account *ancestor);
/** @} */
+/* ------------------ */
+
+/** @name Account kvp_frame getters/setters */
+/** @{ */
+kvp_frame * xaccAccountGetSlots (Account *account);
+void xaccAccountSetSlots_nc(Account *account, kvp_frame *frame);
+
+/** Delete any old data in the account's kvp data.
+ * This includes the old currency and security fields. */
+void xaccAccountDeleteOldData (Account *account);
+/** @} */
+
+/* ------------------ */
+
+/** @name GNCAccountType conversion/checking
+ */
+/* @{ */
+/**
+ * Conversion routines for the account types to/from strings
+ * that are used in persistant storage, communications. These
+ * strings should *not* be translated to the local language.
+ * Typical converstion is INCOME -> "INCOME". */
+char * xaccAccountTypeEnumAsString (GNCAccountType type);
+/**
+ * Conversion routines for the account types to/from strings
+ * that are used in persistant storage, communications. These
+ * strings should *not* be translated to the local language.
+ * Typical converstion is INCOME -> "INCOME". */
+gboolean xaccAccountStringToType (const char* str, GNCAccountType *type);
+/**
+ * Conversion routines for the account types to/from strings
+ * that are used in persistant storage, communications. These
+ * strings should *not* be translated to the local language.
+ * Typical converstion is INCOME -> "INCOME". */
+GNCAccountType xaccAccountStringToEnum (const char* str);
+
+/** The xaccAccountGetTypeStr() routine returns a string suitable for
+ * use in the GUI/Interface. These strings should be translated
+ * to the local language. */
+const char * xaccAccountGetTypeStr (GNCAccountType type);
+/** The xaccAccountGetTypeStr() routine returns a string suitable for
+ * use in the GUI/Interface. These strings should be translated
+ * to the local language. */
+GNCAccountType xaccAccountGetTypeFromStr (const gchar *str);
+
+/** Return TRUE if accounts of type parent_type can have accounts
+ * of type child_type as children. */
+gboolean xaccAccountTypesCompatible (GNCAccountType parent_type,
+ GNCAccountType child_type);
+/* @} */
+
+/* ------------------ */
+
+/* Doxygen note: if these typedefs are inside the member group, the
+ * member group will show up at the top of the documentation, which is
+ * probably not wanted. */
+/** \warning Unimplemented, for xaccAccountForEachSplit() */
+typedef gpointer (*SplitCallback)(Split *s, gpointer data);
+/** Callback prototype for xaccAccountForEachTransaction() */
+typedef gboolean (*TransactionCallback)(Transaction *t, void *data);
+
+/** @name Account split/transaction list management */
+/*@{*/
+/** The xaccAccountInsertSplit() method will insert the indicated
+ * split into the indicated account. If the split already
+ * belongs to another account, it will be removed from that
+ * account first.*/
+void xaccAccountInsertSplit (Account *account, Split *split);
+
/** The xaccAccountGetSplitList() routine returns a pointer to a GList of
* the splits in the account.
* @note This GList is the account's internal
@@ -363,6 +423,82 @@ gboolean xaccAccountGetReconcileChildrenStatus(Account *account);
* pointer. */
SplitList* xaccAccountGetSplitList (Account *account);
+/** \warning Unimplemented */
+gpointer xaccAccountForEachSplit(Account *account,
+ SplitCallback,
+ gpointer data);
+
+/** The xaccAccountForEachTransaction() routine will traverse all of
+ the transactions in the given 'account' and call the callback
+ function 'proc' on each transaction. Processing will continue
+ if-and-only-if 'proc' does not return FALSE. The user data pointer
+ 'data' will be passed on to the callback function 'proc'.
+
+ This function does not descend recursively to traverse transactions
+ in child accounts.
+
+ 'proc' will be called exactly once for each transaction that is
+ pointed to by at least one split in the given account.
+
+ Note too, that if you call this function on two separate accounts
+ and those accounts share transactions, proc will be called once per
+ account for the shared transactions.
+
+ The result of this function will not be FALSE if-and-only-if
+ every relevant transaction was traversed exactly once.
+*/
+gboolean
+xaccAccountForEachTransaction(Account *account,
+ TransactionCallback proc,
+ void *data);
+
+/** The xaccAccountVisitUnvisitedTransactions() routine will
+ visit every transaction in the account that hasn't already been
+ visited exactly once. visited_txns must be a hash table created
+ via guid_hash_table_new() and is the authority about which
+ transactions have already been visited. Further, when this
+ procedure returns visited_txns will have been modified to reflect
+ all the newly visited transactions.
+
+ The result of this function will not be FALSE if-and-only-if
+ every relevant transaction was traversed exactly once.
+*/
+gboolean
+xaccAccountVisitUnvisitedTransactions(Account *account,
+ TransactionCallback,
+ void *data,
+ GHashTable *visited_txns);
+
+/** Returns a pointer to the transaction, not a copy. */
+Transaction *
+xaccAccountFindTransByDesc(Account *account, const char *description);
+/** Returns a pointer to the split, not a copy. */
+Split *
+xaccAccountFindSplitByDesc(Account *account, const char *description);
+
+/** The xaccAccountFixSplitDateOrder() subroutine checks to see if
+ * a split is in proper sorted date order with respect
+ * to the other splits in this account. */
+void xaccAccountFixSplitDateOrder (Account *account, Split *split);
+
+/** The xaccTransFixSplitDateOrder() checks to see if
+ * all of the splits in this transaction are in
+ * proper date order. */
+void xaccTransFixSplitDateOrder (Transaction *trans);
+/*@}*/
+
+/* ------------------ */
+
+/** @name Account lots */
+/*@{*/
+/** The xaccAccountInsertLot() method will register the indicated lot
+ * with this account. Any splits later inserted into this lot must
+ * belong to this account. If the lot is already in another account,
+ * the lot, and all of the splits in it, will be moved from that
+ * account to this account. */
+void xaccAccountInsertLot (Account *, GNCLot *);
+void xaccAccountRemoveLot (Account *, GNCLot *);
+
/** The xaccAccountGetLotList() routine returns a pointer to the GList of
* the lots in this account. The same warnings as above apply. */
LotList* xaccAccountGetLotList (Account *account);
@@ -377,85 +513,10 @@ LotList * xaccAccountFindOpenLots (Account *acc,
gpointer user_data),
gpointer user_data, GCompareFunc sort_func);
-/** @name Account Tax related getters/setters */
-/** @{ */
+/*@}*/
-/** DOCUMENT ME! */
-gboolean xaccAccountGetTaxRelated (Account *account);
-/** DOCUMENT ME! */
-void xaccAccountSetTaxRelated (Account *account,
- gboolean tax_related);
-/** DOCUMENT ME! */
-const char * xaccAccountGetTaxUSCode (Account *account);
-/** DOCUMENT ME! */
-void xaccAccountSetTaxUSCode (Account *account, const char *code);
-/** DOCUMENT ME! */
-const char * xaccAccountGetTaxUSPayerNameSource (Account *account);
-/** DOCUMENT ME! */
-void xaccAccountSetTaxUSPayerNameSource (Account *account,
- const char *source);
-/** @} */
-
-/** @name Account Placeholder getters/setters */
-/** @{ */
-
-/** DOCUMENT ME! */
-typedef enum
- {
- PLACEHOLDER_NONE,
- PLACEHOLDER_THIS,
- PLACEHOLDER_CHILD,
- } GNCPlaceholderType;
-
-/** DOCUMENT ME! */
-gboolean xaccAccountGetPlaceholder (Account *account);
-/** DOCUMENT ME! */
-void xaccAccountSetPlaceholder (Account *account,
- gboolean option);
-/** DOCUMENT ME! */
-GNCPlaceholderType xaccAccountGetDescendantPlaceholder (Account *account);
-/** @} */
-
-/** The xaccAccountGetFullName routine returns the fully qualified name
- * of the account using the given separator char. The name must be
- * g_free'd after use. The fully qualified name of an account is the
- * concatenation of the names of the account and all its ancestor
- * accounts starting with the topmost account and ending with the
- * given account. Each name is separated by the given character.
- *
- * @note: WAKE UP!
- * Unlike all other gets, the string returned by xaccAccountGetFullName()
- * must be freed by you the user !!!
- * hack alert -- since it breaks the rule of string allocation, maybe this
- * routine should not be in this library, but some utility library?
- */
-char * xaccAccountGetFullName (Account *account, const char separator);
-
-/** Returns true if the account has 'ancestor' as an ancestor.
- * Returns false if either is NULL. */
-gboolean xaccAccountHasAncestor (Account *account, Account *ancestor);
-
-/** Set a mark on the account. The meaning of this mark is
- * completely undefined. Its presented here as a utility for the
- * programmer, to use as desired. Handy for performing customer traversals
- * over the account tree. The mark is *not* stored in the database/file
- * format. When accounts are newly created, the mark is set to zero.
- */
-void xaccAccountSetMark (Account *account, short mark);
-
-/** Get the mark set by xaccAccountSetMark */
-short xaccAccountGetMark (Account *account);
-
-/** The xaccClearMark will find the topmost group, and clear the mark in
- * the entire group tree. */
-void xaccClearMark (Account *account, short val);
-
-/** The xaccClearMarkDown will clear the mark only in this and in
- * sub-accounts.*/
-void xaccClearMarkDown (Account *account, short val);
-/** Will clear the mark for all the accounts of the AccountGroup .*/
-void xaccClearMarkDownGr (AccountGroup *group, short val);
+/* ------------------ */
/** @name Account Reconciliation information getters/setters */
/** @{ */
@@ -491,25 +552,108 @@ void xaccAccountSetReconcilePostponeBalance (Account *account,
void xaccAccountClearReconcilePostpone (Account *account);
/** @} */
-/** @name Account AutoInterest getters/setters
- * @note FIXME: What is this? */
+
+/** DOCUMENT ME! */
+typedef enum
+ {
+ PLACEHOLDER_NONE,
+ PLACEHOLDER_THIS,
+ PLACEHOLDER_CHILD,
+ } GNCPlaceholderType;
+
+/** @name Account Placeholder flag */
/** @{ */
/** DOCUMENT ME! */
-gboolean xaccAccountGetAutoInterestXfer (Account *account, gboolean default_value);
+gboolean xaccAccountGetPlaceholder (Account *account);
/** DOCUMENT ME! */
-void xaccAccountSetAutoInterestXfer (Account *account, gboolean option);
+void xaccAccountSetPlaceholder (Account *account,
+ gboolean option);
+/** DOCUMENT ME! */
+GNCPlaceholderType xaccAccountGetDescendantPlaceholder (Account *account);
/** @} */
-/** The xaccAccountSetPriceSrc() and xaccAccountGetPriceSrc() routines
- are used to get and set a string that identifies the Finance::Quote
- backend that should be used to retrieve online prices. See
- price-quotes.scm for more information.*/
-void xaccAccountSetPriceSrc (Account *account, const char *src);
-/** The xaccAccountSetPriceSrc() and xaccAccountGetPriceSrc() routines
- are used to get and set a string that identifies the Finance::Quote
- backend that should be used to retrieve online prices. See
- price-quotes.scm for more information.*/
-const char * xaccAccountGetPriceSrc (Account *account);
+
+/** @name Account Tax related getters/setters */
+/** @{ */
+
+/** DOCUMENT ME! */
+gboolean xaccAccountGetTaxRelated (Account *account);
+/** DOCUMENT ME! */
+void xaccAccountSetTaxRelated (Account *account,
+ gboolean tax_related);
+
+/** DOCUMENT ME! */
+const char * xaccAccountGetTaxUSCode (Account *account);
+/** DOCUMENT ME! */
+void xaccAccountSetTaxUSCode (Account *account, const char *code);
+/** DOCUMENT ME! */
+const char * xaccAccountGetTaxUSPayerNameSource (Account *account);
+/** DOCUMENT ME! */
+void xaccAccountSetTaxUSPayerNameSource (Account *account,
+ const char *source);
+/** @} */
+
+
+/** @name Account marking */
+/*@{*/
+/** Set a mark on the account. The meaning of this mark is
+ * completely undefined. Its presented here as a utility for the
+ * programmer, to use as desired. Handy for performing customer traversals
+ * over the account tree. The mark is *not* stored in the database/file
+ * format. When accounts are newly created, the mark is set to zero.
+ */
+void xaccAccountSetMark (Account *account, short mark);
+
+/** Get the mark set by xaccAccountSetMark */
+short xaccAccountGetMark (Account *account);
+
+/** The xaccClearMark will find the topmost group, and clear the mark in
+ * the entire group tree. */
+void xaccClearMark (Account *account, short val);
+
+/** The xaccClearMarkDown will clear the mark only in this and in
+ * sub-accounts.*/
+void xaccClearMarkDown (Account *account, short val);
+/** Will clear the mark for all the accounts of the AccountGroup .*/
+void xaccClearMarkDownGr (AccountGroup *group, short val);
+/*@}*/
+
+
+/** @name Account deprecated routines. */
+/** @{ */
+
+/** @deprecated The current API associates only one thing with an
+ * account: the 'commodity'. Use xaccAccountGetCommodity() to fetch
+ * it.
+ *
+ * These two funcs take control of their gnc_commodity args. Don't free */
+void DxaccAccountSetCurrency (Account *account, gnc_commodity *currency,
+ GNCBook *book);
+/** @deprecated The current API associates only one thing with an
+ * account: the 'commodity'. Use xaccAccountGetCommodity() to fetch
+ * it.
+ *
+ * These two funcs take control of their gnc_commodity args. Don't free */
+void DxaccAccountSetSecurity (Account *account, gnc_commodity *security,
+ GNCBook *book);
+/** @deprecated The current API associates only one thing with an
+ * account: the 'commodity'. Use xaccAccountGetCommodity() to fetch
+ * it. */
+gnc_commodity * DxaccAccountGetCurrency (Account *account,
+ GNCBook *book);
+/** @deprecated The current API associates only one thing with an
+ * account: the 'commodity'. Use xaccAccountGetCommodity() to fetch
+ * it. */
+gnc_commodity * DxaccAccountGetSecurity (Account *account,
+ GNCBook *book);
+/** @deprecated The current API associates only one thing with an
+ * account: the 'commodity'. Use xaccAccountGetCommodity() to fetch
+ * it. */
+void DxaccAccountSetCurrencySCU (Account *account, int frac);
+/** @deprecated The current API associates only one thing with an
+ * account: the 'commodity'. Use xaccAccountGetCommodity() to fetch
+ * it. */
+int DxaccAccountGetCurrencySCU (Account *account);
/** xaccAccountGetQuoteTZ() and xaccAccountSetQuoteTZ() set the
timezone to be used when interpreting the results from a given
@@ -523,61 +667,9 @@ const char * xaccAccountGetPriceSrc (Account *account);
void xaccAccountSetQuoteTZ (Account *account, const char *tz);
/** @deprecated */
const char * xaccAccountGetQuoteTZ (Account *account);
+/**@}*/
-/** \warning Unimplemented */
-typedef gpointer (*SplitCallback)(Split *s, gpointer data);
-/** \warning Unimplemented */
-gpointer xaccAccountForEachSplit(Account *account,
- SplitCallback,
- gpointer data);
-
-/** Callback prototype */
-typedef gboolean (*TransactionCallback)(Transaction *t, void *data);
-/** The xaccAccountForEachTransaction() routine will
- traverse all of the transactions in the given account. Continue
- processing IFF proc does not return FALSE. This function does not
- descend recursively to traverse transactions in child accounts.
-
- Proc will be called exactly once for each transaction that is
- pointed to by at least one split in the given account.
-
- Note too, that if you call this function on two separate accounts
- and those accounts share transactions, proc will be called once per
- account for the shared transactions.
-
- The result of this function will not be FALSE if-and-only-if
- every relevant transaction was traversed exactly once.
-*/
-gboolean
-xaccAccountForEachTransaction(Account *account,
- TransactionCallback,
- void *data);
-
-/** The xaccAccountVisitUnvisitedTransactions() routine will
- visit every transaction in the account that hasn't already been
- visited exactly once. visited_txns must be a hash table created
- via guid_hash_table_new() and is the authority about which
- transactions have already been visited. Further, when this
- procedure returns visited_txns will have been modified to reflect
- all the newly visited transactions.
-
- The result of this function will not be FALSE if-and-only-if
- every relevant transaction was traversed exactly once.
-*/
-gboolean
-xaccAccountVisitUnvisitedTransactions(Account *account,
- TransactionCallback,
- void *data,
- GHashTable *visited_txns);
-
-/** Returns a pointer to the transaction, not a copy. */
-Transaction *
-xaccAccountFindTransByDesc(Account *account, const char *description);
-/** Returns a pointer to the split, not a copy. */
-Split *
-xaccAccountFindSplitByDesc(Account *account, const char *description);
-
/** @name Account parameter names */
/** @{ */
#define ACCOUNT_KVP "kvp"
@@ -592,7 +684,7 @@ xaccAccountFindSplitByDesc(Account *account, const char *description);
/** @} */
/** This is the type-override when you want to match all accounts. Used
- * in the gnome-search parameter list. Be carefull when you use this. */
+ * in the gnome-search parameter list. Be careful when you use this. */
#define ACCOUNT_MATCH_ALL_TYPE "account-match-all"
#endif /* XACC_ACCOUNT_H */
diff --git a/src/engine/kvp_doc.txt b/src/engine/kvp_doc.txt
index d1d6f4a549..8bdc384d5b 100644
--- a/src/engine/kvp_doc.txt
+++ b/src/engine/kvp_doc.txt
@@ -329,4 +329,40 @@ that it should only exist if the parent transaction has been voided (but
checking the reconcile status of the split is a more direct way of finding
out a split has been voided).
+-----------------------
+
+Name: /hbci
+Type: frame
+Entitites: Account, Book
+Use: subdirectory for information related to the German online banking
+protocol HBCI
+
+Name: /hbci/account-id
+Type: string
+Entities: Account
+Use: HBCI Account code of the HBCI counterpart of this gnucash account
+in the real world
+
+Name: /hbci/bank-code
+Type: string
+Entitites: Account
+Use: Bank code of HBCI account
+
+Name: /hbci/country-code
+Type: gint64
+Entitites: Account
+Use: Country code of the bank of HBCI account
+
+Name: /hbci/trans-retrieval
+Type: Timespec
+Entities: Account
+Use: Time of the last statement retrieval through HBCI for this
+specific account
+
+Name: /hbci/config-filename
+Type: string
+Entitied: Book
+Use: OpenHBCI configuration file name, where the real HBCI
+configuration for the OpenHBCI library can be found
+
--------------------------- end of document ------------------------