From 8b98f87cc5050e26581d874f6217f4d4f081b647 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benoit=20Gr=C3=A9goire?= Date: Sat, 7 Dec 2002 21:16:01 +0000 Subject: [PATCH] =?UTF-8?q?2002-12-7=20=20Benoit=20Gr=EF=BF=BDgoire=20=20=20=09More=20Doxygenification.=20=20Create?= =?UTF-8?q?d=20an=20Engine=20module,=20and=20a=20=09Deprecated=20list.=20?= =?UTF-8?q?=20Unfortunately,=20unless=20we=20turn=20on=20EXTRACT=5FALL=20?= =?UTF-8?q?=09(not=20very=20practical=20currently)=20not=20all=20functions?= =?UTF-8?q?=20will=20appear=20=09unless=20they=20are=20all=20documented.?= =?UTF-8?q?=20=09*=20src/engine/Transaction.h:=20More=20Doxygenification?= =?UTF-8?q?=20=09*=20src/engine/Account.h:=20Doxygenify=20=09*=20src/doc/d?= =?UTF-8?q?oxygen.cfg.in:=20Minor=20config=20change.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@7646 57a11ea4-9604-0410-9ed3-97b8803252fd --- src/doc/doxygen.cfg.in | 2 +- src/engine/Account.h | 402 ++++++++++++++++++++------------------ src/engine/Transaction.h | 412 +++++++++++++++++++++------------------ 3 files changed, 442 insertions(+), 374 deletions(-) diff --git a/src/doc/doxygen.cfg.in b/src/doc/doxygen.cfg.in index 189f14f064..3644b234ca 100644 --- a/src/doc/doxygen.cfg.in +++ b/src/doc/doxygen.cfg.in @@ -9,7 +9,7 @@ OUTPUT_DIRECTORY = OUTPUT_LANGUAGE = English EXTRACT_ALL = NO EXTRACT_PRIVATE = NO -EXTRACT_STATIC = YES +EXTRACT_STATIC = NO EXTRACT_LOCAL_CLASSES = NO HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO diff --git a/src/engine/Account.h b/src/engine/Account.h index 47f54cb499..e70bdf5a79 100644 --- a/src/engine/Account.h +++ b/src/engine/Account.h @@ -1,8 +1,4 @@ /********************************************************************\ - * Account.h -- Account handling public routines * - * Copyright (C) 1997 Robin D. Clark * - * Copyright (C) 1997-2002 Linas Vepstas * - * * * 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 * @@ -21,6 +17,13 @@ * Boston, MA 02111-1307, USA gnu@gnu.org * * * \********************************************************************/ +/** @addtogroup Engine + @{ */ +/** @file Account.h + @brief Account handling public routines + @author Copyright (C) 1997 Robin D. Clark + @author Copyright (C) 1997-2002 Linas Vepstas +*/ #ifndef XACC_ACCOUNT_H #define XACC_ACCOUNT_H @@ -32,154 +35,149 @@ -/** ENUMS ******************************************************/ -/* - * The account types are used to determine how the transaction data +/** The account types are used to determine how the transaction data * in the account is displayed. These values can be safely changed * from one release to the next. Note that if values are added, * the file IO translation routines need to be updated. Note * also that GUI code depends on these numbers. * - * ***IMPORTANT***: If you do change the enumeration names (not the + * @note ***IMPORTANT***: If you do change the enumeration names (not the * numbers), you need to update xaccAccountTypeEnumAsString --- used * for text file exports */ typedef enum { BAD_TYPE = -1, - NO_TYPE = -1, - /* Not a type */ + NO_TYPE = -1,/**< Not a type */ + + BANK = 0, /**< The bank account type denotes a savings or checking account + * held at a bank. Often interest bearing. */ + CASH = 1,/**< The cash account type is used to denote a shoe-box or pillowcase + * stuffed with cash. */ + CREDIT = 3, /**< The Credit card account is used to denote credit (e.g. amex) + * and debit (e.g. visa, mastercard) card accounts */ + ASSET = 2, /**< asset (and liability) accounts indicate generic, generalized accounts + * that are none of the above. */ + LIABILITY = 4, /**< liability (and asset) accounts indicate generic, generalized accounts + * that are none of the above. */ + STOCK = 5, /**< Stock accounts will typically be shown in registers + * 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?*/ + INCOME = 8, /**< Income accounts are used to denote income */ + + EXPENSE = 9,/**< Expense accounts are used to denote expenses. */ + + EQUITY = 10,/**< Equity account is used to balance the balance sheet. */ + + RECEIVABLE = 11, /**< A/R account type */ - BANK = 0, - /* The bank account type denotes a savings or checking account - * held at a bank. Often interest bearing. - */ - - CASH = 1, - /* The cash account type is used to denote a shoe-box or pillowcase - * stuffed with cash. - */ - - CREDIT = 3, - /* The Credit card account is used to denote credit (e.g. amex) and - * debit (e.g. visa, mastercard) card accounts - */ - - ASSET = 2, - LIABILITY = 4, - /* asset and liability accounts indicate generic, generalized accounts - * that are none of the above. - */ - - STOCK = 5, - MUTUAL= 6, - /* Stock and 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. - */ - - INCOME = 8, - EXPENSE = 9, - /* Income and expense accounts are used to denote income and expenses. */ - - EQUITY = 10, - /* Equity account is used to balance the balance sheet. */ - - RECEIVABLE = 11, - PAYABLE = 12, - /* A/R and A/P account types */ - - NUM_ACCOUNT_TYPES = 13, - /* stop here; the following types just aren't ready for prime time */ + PAYABLE = 12, /**< A/P account type */ + NUM_ACCOUNT_TYPES = 13, /**< stop here; the following types + * just aren't ready for prime time */ + /* bank account types */ CHECKING = 13, SAVINGS = 14, MONEYMRKT = 15, - CREDITLINE = 16, /* line of credit */ + CREDITLINE = 16, /**< line of credit */ } GNCAccountType; -/* ------------------ */ -/* The xaccAccountGetTypeStr() routine returns a string suitable for - * use in the GUI/Interface. These strings should be translated - * to the local language. - */ + +/** 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". - */ + * 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 +/** 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 ******************************************************/ -/* - * The xaccAccountBeginEdit() and xaccAccountCommitEdit() subroutines - * provide a two-phase-commit wrapper for account updates. - * - * The xaccAccountDestroy() routine can be used to get rid of an - * account. The account should have been opened for editing - * (by calling xaccAccountBeginEdit()) before calling this routine. - * - * The xaccCloneAccountSimple() routine makes a simple copy of the - * indicated account, placing it in the indicated book. It copies - * the account type, name, description, and the kvp values; - * it does not copy splits/transactions. Note also that it - * does NOT use the 'gemini' kvp value to indicate where it - * was copied from. - * - * The xaccCloneAccount() does teh same as above, except that it - * also uses the 'gemini' kvp value to mark the account from - * which it was copied. - */ +/* PROTOTYPES ******************************************************/ + +/** @name Account Constructors/Destructors and Edit/Commit */ +/** @{ */ + +/** Constructor */ Account * xaccMallocAccount (GNCBook *book); + +/** The xaccCloneAccount() does the same as xaccCloneAccountSimple, except that it + * also uses the 'gemini' kvp value to mark the account from + * which it was copied. */ Account * xaccCloneAccount (const Account *from, GNCBook *book); + +/** The xaccCloneAccountSimple() routine makes a simple copy of the + * indicated account, placing it in the indicated book. It copies + * the account type, name, description, and the kvp values; + * it does not copy splits/transactions. Note also that it + * does NOT use the 'gemini' kvp value to indicate where it + * was copied from.*/ Account * xaccCloneAccountSimple (const Account *from, GNCBook *book); +/** The xaccAccountBeginEdit() subroutine is the first phase of + * a two-phase-commit wrapper for account updates. */ void xaccAccountBeginEdit (Account *account); + +/** ThexaccAccountCommitEdit() subroutine is the second phase of + * a two-phase-commit wrapper for account updates. */ void xaccAccountCommitEdit (Account *account); + +/** The xaccAccountDestroy() routine can be used to get rid of an + * account. The account should have been opened for editing + * (by calling xaccAccountBeginEdit()) before calling this routine.*/ void xaccAccountDestroy (Account *account); +/** @} */ + +/** @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); -/* ------------------ */ -/* - * The xaccAccountGetGUID() subroutine will return the - * globally unique id associated with that account. - * xaccAccountReturnGUID() returns the same as a - * struct. - * - * The xaccAccountLookup() subroutine will return the - * account associated with the given id, or NULL - * if there is no such account. - * xaccAccountLookupDirect performs the same - * function but takes a GUID struct directly. - */ -const GUID * xaccAccountGetGUID (Account *account); -GUID xaccAccountReturnGUID (Account *account); -Account * xaccAccountLookup (const GUID *guid, GNCBook *book); -Account * xaccAccountLookupDirect (GUID guid, GNCBook *book); +/** @name Account GUID subroutines */ +/** @{ */ -/* The xaccAccountLookupTwin() routine will find the +/** The xaccAccountGetGUID() subroutine will return the + * globally unique id associated with that account. */ +const GUID * xaccAccountGetGUID (Account *account); + /** The xaccAccountReturnGUID() subroutine returns the + * same GUID as xaccAccountGetGUID, but as a struct. */ +GUID xaccAccountReturnGUID (Account *account); + +/** The xaccAccountLookup() subroutine will return the + * account associated with the given id, or NULL + * if there is no such account. */ +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 (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 @@ -190,44 +188,39 @@ Account * xaccAccountLookupDirect (GUID guid, GNCBook *book); * 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. - */ + * 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. */ +/** 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 +/** 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. - */ + * account to this account. */ void xaccAccountInsertLot (Account *, GNCLot *); -/* - * The xaccAccountInsertSplit() method will insert the indicated +/** 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. - */ + * account first.*/ void xaccAccountInsertSplit (Account *account, Split *split); -/* The xaccAccountFixSplitDateOrder() subroutine checks to see if +/** The xaccAccountFixSplitDateOrder() subroutine checks to see if * a split is in proper sorted date order with respect - * to the other splits in this account. - * - * The xaccTransFixSplitDateOrder() checks to see if - * all of the splits in this transaction are in - * proper date order. - */ + * 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 +/** 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 @@ -237,19 +230,27 @@ void xaccTransFixSplitDateOrder (Transaction *trans); */ int xaccAccountOrder (Account **account_1, Account **account_2); +/** @name Account general setters/getters */ +/** @{ */ void xaccAccountSetType (Account *account, GNCAccountType); void xaccAccountSetName (Account *account, const char *name); void xaccAccountSetCode (Account *account, const char *code); void xaccAccountSetDescription (Account *account, const char *desc); void xaccAccountSetNotes (Account *account, const char *notes); +/** Set the last num field of an Account */ +void xaccAccountSetLastNum (Account *account, const char *num); GNCAccountType xaccAccountGetType (Account *account); const char * xaccAccountGetName (Account *account); const char * xaccAccountGetCode (Account *account); const char * xaccAccountGetDescription (Account *account); const char * xaccAccountGetNotes (Account *account); +const char * xaccAccountGetLastNum (Account *account); +/** @} */ -/* New commodity access routines. +/* @name Account Commodity setters/getters + * + * New commodity access routines. * * The account structure no longer stores two commodities ('currency' * and 'security'). Instead it stores only one commodity, that is the @@ -261,59 +262,74 @@ const char * xaccAccountGetNotes (Account *account); * 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. */ +/** @{ */ void xaccAccountSetCommodity (Account *account, gnc_commodity *comm); gnc_commodity * xaccAccountGetCommodity (Account *account); int xaccAccountGetCommoditySCU (Account *account); void xaccAccountSetCommoditySCU (Account *account, int frac); -/* Deprecated currency/security access routines. - * 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 */ + +gnc_numeric xaccAccountGetBalance (Account *account); +gnc_numeric xaccAccountGetClearedBalance (Account *account); +gnc_numeric xaccAccountGetReconciledBalance (Account *account); +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. +/** 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 */ +/** @{ */ AccountGroup * xaccAccountGetChildren (Account *account); AccountGroup * xaccAccountGetParent (Account *account); Account * xaccAccountGetParentAccount (Account *account); GList * xaccAccountGetDescendants (Account *account); -gnc_numeric xaccAccountGetBalance (Account *account); -gnc_numeric xaccAccountGetClearedBalance (Account *account); -gnc_numeric xaccAccountGetReconciledBalance (Account *account); - void xaccAccountSetReconcileChildrenStatus(Account *account, gboolean status); gboolean xaccAccountGetReconcileChildrenStatus(Account *account); +/** @} */ -gnc_numeric xaccAccountGetBalanceAsOfDate (Account *account, time_t date); - -/* The xaccAccountGetSplitList() routine returns a pointer to a GList of - * the splits in the account. This GList is the account's internal +/** The xaccAccountGetSplitList() routine returns a pointer to a GList of + * the splits in the account. + * @note This GList is the account's internal * data structure: do not delete it when done; treat it as a read-only * structure. Note that some routines (such as xaccAccountRemoveSplit()) * modify this list directly, and could leave you with a corrupted - * pointer. - * - * The xaccAccountGetLotList() routine returns a pointer to the GList of - * the lots in this account. The same warnings as above apply. - */ + * pointer. */ SplitList* xaccAccountGetSplitList (Account *account); + + /** 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); -/* Find a list of open lots that match the match_func. Sort according +/** Find a list of open lots that match the match_func. Sort according * to sort_func. If match_func is NULL, then all open lots are returned. * If sort_func is NULL, then the returned list has no particular order. * The caller must free to returned list. @@ -323,6 +339,8 @@ LotList * xaccAccountFindOpenLots (Account *acc, gpointer user_data), gpointer user_data, GCompareFunc sort_func); +/** @name Account Tax related getters/setters */ +/** @{ */ gboolean xaccAccountGetTaxRelated (Account *account); void xaccAccountSetTaxRelated (Account *account, gboolean tax_related); @@ -332,27 +350,31 @@ void xaccAccountSetTaxUSCode (Account *account, const char *code); const char * xaccAccountGetTaxUSPayerNameSource (Account *account); void xaccAccountSetTaxUSPayerNameSource (Account *account, const char *source); +/** @} */ +/** @name Account Placeholder getters/setters */ +/** @{ */ typedef enum -{ + { PLACEHOLDER_NONE, PLACEHOLDER_THIS, PLACEHOLDER_CHILD, -} GNCPlaceholderType; + } GNCPlaceholderType; gboolean xaccAccountGetPlaceholder (Account *account); void xaccAccountSetPlaceholder (Account *account, gboolean option); GNCPlaceholderType xaccAccountGetDescendantPlaceholder (Account *account); +/** @} */ -/* The xaccAccountGetFullName routine returns the fully qualified name +/** 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. * - * WAKE UP! + * @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 @@ -360,28 +382,33 @@ GNCPlaceholderType xaccAccountGetDescendantPlaceholder (Account *account); */ char * xaccAccountGetFullName (Account *account, const char separator); -/* Returns true if the account has 'ancestor' as an ancestor. +/** Returns true if the account has 'ancestor' as an ancestor. * Returns false if either is NULL. */ gboolean xaccAccountHasAncestor (Account *account, Account *ancestor); -/* Get and Set a mark on the account. The meaning of this mark is +/** 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. - * - * The xaccClearMark will find the topmost group, and clear the mark in - * the entire group tree. - * The xaccClearMarkDown will clear the mark only in this and in - * sub-accounts. */ -short xaccAccountGetMark (Account *account); 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); -/* The following functions get and set reconciliation information */ +/** @name Account Reconciliation information getters/setters */ +/** @{ */ gboolean xaccAccountGetReconcileLastDate (Account *account, time_t *last_date); void xaccAccountSetReconcileLastDate (Account *account, @@ -403,43 +430,45 @@ void xaccAccountSetReconcilePostponeBalance (Account *account, gnc_numeric balance); void xaccAccountClearReconcilePostpone (Account *account); +/** @} */ +/** @name Account AutoInterest getters/setters + * @note FIXME: What is this? */ +/** @{ */ gboolean xaccAccountGetAutoInterestXfer (Account *account, gboolean default_value); void xaccAccountSetAutoInterestXfer (Account *account, gboolean option); +/** @} */ -/* Get and set the last num field of an Account */ -const char * xaccAccountGetLastNum (Account *account); -void xaccAccountSetLastNum (Account *account, const char *num); - -/* 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. - - xaccAccountGetQuoteTZ() and xaccAccountSetQuoteTZ() set the - timezone to be used when interpreting the results from a given - Finance::Quote backend. Unfortunately, the upstream sources don't - label their output, so the user has to specify this bit. - - Since prices are not going to be stored in the accounts in the - future, and since the whole commodities infrastructure is changing - radically as we speak, this interface is not long for this - world. */ - +/** 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); const char * xaccAccountGetPriceSrc (Account *account); +/** xaccAccountGetQuoteTZ() and xaccAccountSetQuoteTZ() set the + timezone to be used when interpreting the results from a given + Finance::Quote backend. Unfortunately, the upstream sources don't + label their output, so the user has to specify this bit. + + @deprecated Since prices are not going to be stored in the accounts in the + future, and since the whole commodities infrastructure is changing + radically as we speak, this interface is not long for this + world. */ void xaccAccountSetQuoteTZ (Account *account, const char *tz); +/** @deprecated */ const char * xaccAccountGetQuoteTZ (Account *account); -/* Unimplemented */ +/** Unimplemented */ typedef gpointer (*SplitCallback)(Split *s, gpointer data); +/** Unimplemented */ gpointer xaccAccountForEachSplit(Account *account, SplitCallback, gpointer data); -/* The xaccAccountForEachTransaction() routine will +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. @@ -454,13 +483,12 @@ gpointer xaccAccountForEachSplit(Account *account, The result of this function will not be FALSE if-and-only-if every relevant transaction was traversed exactly once. */ -typedef gboolean (*TransactionCallback)(Transaction *t, void *data); gboolean xaccAccountForEachTransaction(Account *account, TransactionCallback, void *data); -/* The xaccAccountVisitUnvisitedTransactions() routine will +/** 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 @@ -477,14 +505,15 @@ xaccAccountVisitUnvisitedTransactions(Account *account, void *data, GHashTable *visited_txns); -/* Returns a pointer to the transaction, not a copy. */ +/** 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); -/* Account parameter names */ - +/** @name Account parameter names */ +/** @{ */ #define ACCOUNT_KVP "kvp" #define ACCOUNT_NAME_ "name" #define ACCOUNT_CODE_ "code" @@ -494,10 +523,11 @@ xaccAccountFindSplitByDesc(Account *account, const char *description); #define ACCOUNT_CLEARED_BALANCE "cleared-balance" #define ACCOUNT_RECONCILED_BALANCE "reconciled-balance" #define ACCOUNT_TAX_RELATED "tax-related-p" +/** @} */ -/* This is the type-override when you want to match all accounts. Used - * in the gnome-search parameter list. Be carefule when you use this. - */ +/** 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. */ #define ACCOUNT_MATCH_ALL_TYPE "account-match-all" #endif /* XACC_ACCOUNT_H */ +/** @} */ diff --git a/src/engine/Transaction.h b/src/engine/Transaction.h index 864ff03eb6..6cf21af16c 100644 --- a/src/engine/Transaction.h +++ b/src/engine/Transaction.h @@ -1,8 +1,4 @@ /********************************************************************\ - * Transaction.h -- api for transactions & splits (journal entries) * - * Copyright (C) 1997 Robin D. Clark * - * Copyright (C) 1997-2001 Linas Vepstas * - * * * 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 * @@ -21,10 +17,13 @@ * Boston, MA 02111-1307, USA gnu@gnu.org * * * \********************************************************************/ - +/** @addtogroup Engine + @{ */ /** @file Transaction.h - * @brief API for Transaction and Split - */ + @brief API for Transactions and Splits (journal entries) + @author Copyright (C) 1997 Robin D. Clark + @author Copyright (C) 1997-2001 Linas Vepstas +*/ #ifndef XACC_TRANSACTION_H #define XACC_TRANSACTION_H @@ -37,27 +36,29 @@ #include "GNCId.h" #include "date.h" +/** @name Split Reconciled field values + If you change these + be sure to change gnc-ui-util.c:gnc_get_reconciled_str() and + associated functions +*/ +/**@{*/ +#define CREC 'c' /**< The Split has been cleared */ +#define YREC 'y' /**< The Split has been reconciled */ +#define FREC 'f' /**< frozen into accounting period */ +#define NREC 'n' /**< not reconciled or cleared */ +#define VREC 'v' /**< split is void */ +/**@}*/ -/* Values for the reconciled field in Splits.. If you change these - * be sure to change gnc-ui-util.c:gnc_get_reconciled_str() and - * associated functions - */ -#define CREC 'c' /* The Split has been cleared */ -#define YREC 'y' /* The Split has been reconciled */ -#define FREC 'f' /* frozen into accounting period */ -#define NREC 'n' /* not reconciled or cleared */ -#define VREC 'v' /* split is void */ - - -/* Values for the Transaction Type field in Transactions */ -#define TXN_TYPE_NONE '\0' -#define TXN_TYPE_INVOICE 'I' -#define TXN_TYPE_PAYMENT 'P' - +/** @name Transaction Type field values */ +/**@{*/ +#define TXN_TYPE_NONE '\0' /**< No transaction type */ +#define TXN_TYPE_INVOICE 'I' /**< Transaction is an invoice */ +#define TXN_TYPE_PAYMENT 'P' /**< Transaction is a payment */ +/**@}*/ /** PROTOTYPES ******************************************************/ -/* +/** @name Transaction ForceDoubleEntry getters/setters * The xaccConfigSetForceDoubleEntry() and xaccConfigGetForceDoubleEntry() * set and get the "force_double_entry" flag. This flag determines how * the splits in a transaction will be balanced. @@ -73,145 +74,120 @@ * 2 -- splits without parents will be forced into a * lost & found account. (Not implemented) */ - +/**@{*/ void xaccConfigSetForceDoubleEntry (int force); int xaccConfigGetForceDoubleEntry (void); +/**@}*/ -/* - * The xaccMallocTransaction() will malloc memory and initialize it. - * Once created, it is usually unsafe to merely "free" this memory; - * the xaccTransDestroy() method should be called. - */ +/** + The xaccMallocTransaction() will malloc memory and initialize it. + Once created, it is usually unsafe to merely "free" this memory; + the xaccTransDestroy() method should be called. */ Transaction * xaccMallocTransaction (GNCBook *book); +/** + The xaccTransDestroy() method will remove all + of the splits from each of their accounts, free the memory + associated with them. This routine must be followed by either + an xaccTransCommitEdit(), in which case the transaction + memory will be freed, or by xaccTransRollbackEdit(), in which + case nothing at all is freed, and everything is put back into + original order. */ +void xaccTransDestroy (Transaction *trans); + +/** @brief DOCUMENT ME!*/ gboolean xaccTransEqual(const Transaction *ta, const Transaction *tb, gboolean check_guids, gboolean check_splits); - -/* The xaccTransDestroy() method will remove all - * of the splits from each of their accounts, free the memory - * associated with them. This routine must be followed by either - * an xaccTransCommitEdit(), in which case the transaction - * memory will be freed, or by xaccTransRollbackEdit(), in which - * case nothing at all is freed, and everything is put back into - * original order. - */ -void xaccTransDestroy (Transaction *trans); - -/* The xaccTransBeginEdit() method must be called before any changes - * are made to a transaction or any of its component splits. If - * this is not done, errors will result. - * - * The xaccTransCommitEdit() method indicates that the changes to the - * transaction and its splits are complete and should be made - * permanent. Note this routine may result in the deletion of the - * transaction, if the transaction is "empty" (has no splits), or - * of xaccTransDestroy() was called on the transaction. - * - * The xaccTransRollbackEdit() routine rejects all edits made, and - * sets the transaction back to where it was before the editing - * started. This includes restoring any deleted splits, removing - * any added splits, and undoing the effects of xaccTransDestroy, - * as well as restoring share quantities, memos, descriptions, etc. - * - * The xaccTransIsOpen() method returns TRUE if the transaction - * is open for editing. Otherwise, it returns false. */ +/** The xaccTransBeginEdit() method must be called before any changes + are made to a transaction or any of its component splits. If + this is not done, errors will result. */ void xaccTransBeginEdit (Transaction *trans); + +/** The xaccTransCommitEdit() method indicates that the changes to the + transaction and its splits are complete and should be made + permanent. Note this routine may result in the deletion of the + transaction, if the transaction is "empty" (has no splits), or + of xaccTransDestroy() was called on the transaction. */ void xaccTransCommitEdit (Transaction *trans); + +/** The xaccTransRollbackEdit() routine rejects all edits made, and + sets the transaction back to where it was before the editing + started. This includes restoring any deleted splits, removing + any added splits, and undoing the effects of xaccTransDestroy, + as well as restoring share quantities, memos, descriptions, etc. */ void xaccTransRollbackEdit (Transaction *trans); +/** The xaccTransIsOpen() method returns TRUE if the transaction + is open for editing. Otherwise, it returns false. */ gboolean xaccTransIsOpen (const Transaction *trans); -/* - * The xaccTransGetGUID() subroutine will return the - * globally unique id associated with that transaction. - * xaccTransReturnGUID() does the same thing but - * returns a GUID struct. - * - * The xaccTransLookup() subroutine will return the - * transaction associated with the given id, or NULL - * if there is no such transaction. - */ +/** The xaccTransGetGUID() subroutine will return the + globally unique id associated with that transaction. */ const GUID * xaccTransGetGUID (const Transaction *trans); + +/** xaccTransReturnGUID() will returns a GUID struct + associated with that transaction. */ GUID xaccTransReturnGUID (const Transaction *trans); + +/** The xaccTransLookup() subroutine will return the + transaction associated with the given id, or NULL + if there is no such transaction. */ Transaction * xaccTransLookup (const GUID *guid, GNCBook *book); Transaction * xaccTransLookupDirect (GUID guid, GNCBook *book); + +/** Returns the book in which the transaction is stored */ GNCBook * xaccTransGetBook (const Transaction *trans); -/* Transaction slots are used to store arbitrary strings, numbers, and - * structures which aren't members of the transaction struct. */ +/** @name Transaction KVP frames setters/getters + * + Transaction slots are used to store arbitrary strings, numbers, and + structures which aren't members of the transaction struct. */ + +/**@{*/ kvp_frame *xaccTransGetSlots(const Transaction *trans); void xaccTransSetSlots_nc(Transaction *t, kvp_frame *frm); +/**@}*/ -/* The xaccTransSetDateSecs() method will modify the posted date of - * the transaction, specified by a time_t (see ctime(3)). - * xaccTransSetDatePostedSecs() is just an alias for - * xaccTransSetDateSecs() -- both functions access the same date. +/** @name Transaction date setters/getters * - * (Footnote: this shouldn't matter to a user, but anyone modifying - * the engine should understand that when xaccTransCommitEdit() is - * called, the date order of each of the component splits will be - * checked, and will be restored in ascending date order.) - * - * The xaccTransSetDate() method does the same thing as - * xaccTransSetDate[Posted]Secs(), but takes a convenient - * day-month-year format. - * - * The xaccTransSetDatePostedTS() method does the same thing as - * xaccTransSetDate[Posted]Secs(), but takes a struct timespec64. - * - */ + (Footnote: this shouldn't matter to a user, but anyone modifying + the engine should understand that when xaccTransCommitEdit() is + called, the date order of each of the component splits will be + checked, and will be restored in ascending date order.) */ + +/**@{*/ + +/** The xaccTransSetDate() method does the same thing as + xaccTransSetDate[Posted]Secs(), but takes a convenient + day-month-year format.*/ void xaccTransSetDate (Transaction *trans, int day, int mon, int year); + +/** The xaccTransSetDateSecs() method will modify the posted date of + the transaction, specified by a time_t (see ctime(3)). */ void xaccTransSetDateSecs (Transaction *trans, time_t time); + +/** xaccTransSetDatePostedSecs() is just an alias for + xaccTransSetDateSecs() -- both functions access the same date. */ void xaccTransSetDatePostedSecs (Transaction *trans, time_t time); + +/** The xaccTransSetDatePostedTS() method does the same thing as + xaccTransSetDate[Posted]Secs(), but takes a struct timespec64. */ void xaccTransSetDatePostedTS (Transaction *trans, const Timespec *ts); -/* Modify the date of when the transaction was entered. */ +/** @brief Modify the date of when the transaction was entered. */ void xaccTransSetDateEnteredSecs (Transaction *trans, time_t time); +/** @brief Modify the date of when the transaction was entered. */ void xaccTransSetDateEnteredTS (Transaction *trans, - const Timespec *ts); + const Timespec *ts); /* Dates and txn-type for A/R and A/P "invoice" postings */ void xaccTransSetDateDueTS (Transaction *trans, const Timespec *ts); -void xaccTransSetTxnType (Transaction *trans, char type); - -/* set the Num, Description, and Notes fields */ -void xaccTransSetNum (Transaction *trans, const char *num); -void xaccTransSetDescription (Transaction *trans, const char *desc); -void xaccTransSetNotes (Transaction *trans, const char *notes); - -/* The xaccTransAppendSplit() method will append the indicated - * split to the collection of splits in this transaction. - * If the split is already a part of another transaction, - * it will be removed from that transaction first. - */ -void xaccTransAppendSplit (Transaction *trans, Split *split); - -/* ------------- gets --------------- */ -/* The xaccTransGetSplit() method returns a pointer to each of the - * splits in this transaction. Valid values for i are zero to - * (number_of__splits-1). An invalid value of i will cause NULL to - * be returned. A convenient way of cycling through all splits is - * to start at zero, and keep incrementing until a null value is returned. - */ -Split * xaccTransGetSplit (const Transaction *trans, int i); - -/* The xaccTransGetSplitList() method returns a GList of the splits - * in a transaction. This list must not be modified. Do *NOT* free - * this list when you are done with it. */ -SplitList * xaccTransGetSplitList (const Transaction *trans); - -/* These routines return the Num (or ID field), the description, - * the notes, and the date field. - */ -const char * xaccTransGetNum (const Transaction *trans); -const char * xaccTransGetDescription (const Transaction *trans); -const char * xaccTransGetNotes (const Transaction *trans); /* Retrieve the posted date of the transaction. (Although having different function names, GetDate and GetDatePosted refer to the @@ -227,53 +203,115 @@ Timespec xaccTransRetDateEnteredTS (const Transaction *trans); /* Dates and txn-type for A/R and A/P "invoice" postings */ Timespec xaccTransRetDateDueTS (const Transaction *trans); void xaccTransGetDateDueTS (const Transaction *trans, Timespec *ts); -char xaccTransGetTxnType (const Transaction *trans); +/**@}*/ + +/** @name Transaction Type getters/setters + * + See #define TXN_TYPE_NONE, TXN_TYPE_INVOICE and TXN_TYPE_PAYMENT */ +/**@{*/ +void xaccTransSetTxnType (Transaction *trans, char type); +char xaccTransGetTxnType (const Transaction *trans); +/**@}*/ + +/** @name Transaction general getters/setters */ +/**@{*/ + +/* @brief Sets the transaction Number (or ID) field*/ +void xaccTransSetNum (Transaction *trans, const char *num); +/* @brief Sets the transaction Description */ +void xaccTransSetDescription (Transaction *trans, const char *desc); +/* @brief Sets the transaction Notes + * + The Notes field is only visible in the register in double-line mode */ +void xaccTransSetNotes (Transaction *trans, const char *notes); + +/* @brief Gets the transaction Number (or ID) field*/ +const char * xaccTransGetNum (const Transaction *trans); +/* @brief Gets the transaction Description */ +const char * xaccTransGetDescription (const Transaction *trans); +/* @brief Gets the transaction Notes + * + The Notes field is only visible in the register in double-line mode */ +const char * xaccTransGetNotes (const Transaction *trans); + +/**@}*/ + +/** @brief Add a split to the transaction + * + The xaccTransAppendSplit() method will append the indicated + split to the collection of splits in this transaction. + @note If the split is already a part of another transaction, + it will be removed from that transaction first. +*/ +void xaccTransAppendSplit (Transaction *trans, Split *split); + +/** The xaccTransGetSplit() method returns a pointer to each of the + splits in this transaction. + @param trans The transaction + @param i The split number. Valid values for i are zero to + (number_of__splits-1). An invalid value of i will cause NULL to + be returned. A convenient way of cycling through all splits is + to start at zero, and keep incrementing until a null value is returned. */ +Split * xaccTransGetSplit (const Transaction *trans, int i); + +/** The xaccTransGetSplitList() method returns a GList of the splits + in a transaction. + @return The list of splits. This list must NOT be modified. Do *NOT* free + this list when you are done with it. */ +SplitList * xaccTransGetSplitList (const Transaction *trans); + + +/** @name Transaction ReadOnly functions */ +/**@{*/ void xaccTransSetReadOnly (Transaction *trans, const char *reason); const char * xaccTransGetReadOnly (const Transaction *trans); gboolean xaccTransWarnReadOnly (const Transaction *trans); +/**@}*/ -/* The xaccTransCountSplits() method returns the number of splits - * in a transaction. - */ +/** @brief returns the number of splits in a transaction. */ int xaccTransCountSplits (const Transaction *trans); gboolean xaccTransHasReconciledSplits (const Transaction *trans); gboolean xaccTransHasReconciledSplitsByAccount (const Transaction *trans, const Account *account); -/* --------------------------------------------------------------- */ -/* Commmodity routines. Each transaction's 'currency' is by definition + +/** @name Transaction Commmodity routines. + * + * Each transaction's 'currency' is by definition * the balancing common currency for the splits in that transaction. - * */ + * @note What happens if the Currency isn't set? */ +/**@{*/ gnc_commodity * xaccTransGetCurrency (const Transaction *trans); void xaccTransSetCurrency (Transaction *trans, gnc_commodity *curr); +/**@}*/ -/* The xaccTransGetImbalance() method returns the total value of the - * transaction. In a pure double-entry system, this imbalance - * should be exactly zero, and if it is not, something is broken. - * However, when double-entry semantics are not enforced, unbalanced - * transactions can sneak in, and this routine can be used to find - * out how much things are off by. The value returned is denominated - * in the currency that is returned by the xaccTransFindCommonCurrency() - * method. - */ +/** The xaccTransGetImbalance() method returns the total value of the + * transaction. In a pure double-entry system, this imbalance + * should be exactly zero, and if it is not, something is broken. + * However, when double-entry semantics are not enforced, unbalanced + * transactions can sneak in, and this routine can be used to find + * out how much things are off by. The value returned is denominated + * in the currency that is returned by the xaccTransFindCommonCurrency() + * method. */ gnc_numeric xaccTransGetImbalance (const Transaction * trans); -/* The xaccTransGetAccountValue() method returns the total value applied - * to a paricular account. In some cases there may be multiple Splits - * in a single Transaction applied to one account (in particular when - * trying to balance Lots) -- this function is just a convienience to - * view everything at once. +/** The xaccTransGetAccountValue() method returns the total value applied + * to a paricular account. In some cases there may be multiple Splits + * in a single Transaction applied to one account (in particular when + * trying to balance Lots) -- this function is just a convienience to + * view everything at once. */ gnc_numeric xaccTransGetAccountValue (const Transaction *trans, const Account *account); -/************************************************************************ +/*----------------------------------------------------------------------- * Splits - ************************************************************************/ + *-----------------------------------------------------------------------*/ + /** @name Split general getters/setters */ /*@{*/ @@ -357,8 +395,10 @@ void xaccSplitSetAction (Split *split, const char *action); /** Returns the action string. */ const char * xaccSplitGetAction (const Split *split); +/**@}*/ - +/** @name Split Date getters/setters */ +/**@{*/ /** Set the reconcile flag. The Reconcile flag is a single char, whose * values are typically are 'n', 'y', 'c'. In Transaction.h, macros * are defined for typical values (e.g. CREC, YREC). */ @@ -379,7 +419,7 @@ void xaccSplitGetDateReconciledTS (const Split *split, /** Returns the date (as Timespec) on which this split was reconciled. */ Timespec xaccSplitRetDateReconciledTS (const Split *split); -/*@}*/ +/**@}*/ /** @name Split amount getters/setters @@ -437,7 +477,7 @@ gnc_numeric xaccSplitGetSharePrice (const Split * split); * commodity, set the value. If it's the account's commodity, set the * amount. If both, set both. * - * FIXME: is this function deprecated, or is this function supposed to + * @note FIXME: is this function deprecated, or is this function supposed to * be used? */ void xaccSplitSetBaseValue (Split *split, gnc_numeric value, const gnc_commodity * base_currency); @@ -449,13 +489,11 @@ void xaccSplitSetBaseValue (Split *split, gnc_numeric value, * is false, return the value. If is is neither and force_double_entry * is true, print a warning message and return gnc_numeric_zero(). * - * FIXME: is this function deprecated, or is this function supposed to + * @note FIXME: is this function deprecated, or is this function supposed to * be used? */ gnc_numeric xaccSplitGetBaseValue (const Split *split, const gnc_commodity * base_currency); - - /** Returns the running balance up to and including the indicated split. * The balance is the currency-denominated balance. For accounts * with non-unit share prices, it is correctly adjusted for @@ -481,12 +519,12 @@ gnc_numeric xaccSplitGetClearedBalance (const Split *split); */ gnc_numeric xaccSplitGetReconciledBalance (const Split *split); -/*@}*/ +/**@}*/ /** @name Split utility functions */ -/*@{*/ +/**@{*/ /** Equality. * @@ -596,33 +634,33 @@ const char * xaccSplitGetCorrAccountCode(const Split *sa); /** @name Split deprecated functions */ /*@{*/ -/** The xaccSplitSetSharePrice() method sets the price of the +/** @deprecated The xaccSplitSetSharePrice() method sets the price of the * split. DEPRECATED - set the value and amount instead. */ void xaccSplitSetSharePrice (Split *split, gnc_numeric price); -/** DEPRECATED. Don't use doubles anymore, only use gnc_numerics. */ +/** @deprecated Don't use doubles anymore, only use gnc_numerics. */ void DxaccSplitSetAmount (Split *s, double damt); -/** DEPRECATED. Don't use doubles anymore, only use gnc_numerics. +/** @deprecated Don't use doubles anymore, only use gnc_numerics. * * WARNING: The xaccSplitSetValue and DxaccSplitSetValue do NOT have the same * behavior. The later divides the value given by the current value and set's * the result as the new split value. Is that a but or just strange undocumented * feature? Benoit Grégoire 2002-6-12 */ void DxaccSplitSetValue (Split *split, double value); -/** DEPRECATED. Don't use doubles anymore, only use gnc_numerics. */ +/** @deprecated Don't use doubles anymore, only use gnc_numerics. */ double DxaccSplitGetValue (const Split * split); -/** DEPRECATED. Don't use doubles anymore, only use gnc_numerics. */ +/** @deprecated Don't use doubles anymore, only use gnc_numerics. */ void DxaccSplitSetSharePriceAndAmount (Split *split, double price, double amount); -/** DEPRECATED. Don't use doubles anymore, only use gnc_numerics. */ +/** @deprecated Don't use doubles anymore, only use gnc_numerics. */ void DxaccSplitSetShareAmount (Split *split, double amount); -/** DEPRECATED. Don't use doubles anymore, only use gnc_numerics. */ +/** @deprecated Don't use doubles anymore, only use gnc_numerics. */ double DxaccSplitGetShareAmount (const Split * split); -/** DEPRECATED. Don't use doubles anymore, only use gnc_numerics. */ +/** @deprecated Don't use doubles anymore, only use gnc_numerics. */ void DxaccSplitSetSharePrice (Split *split, double price); -/** DEPRECATED. Don't use doubles anymore, only use gnc_numerics. */ +/** @deprecated Don't use doubles anymore, only use gnc_numerics. */ double DxaccSplitGetSharePrice (const Split * split); -/** DEPRECATED. Don't use doubles anymore, only use gnc_numerics. */ +/** @deprecated Don't use doubles anymore, only use gnc_numerics. */ void DxaccSplitSetBaseValue (Split *split, double value, const gnc_commodity * base_currency); /*@}*/ @@ -646,15 +684,12 @@ int xaccTransOrder (const Transaction *ta, const Transaction *tb); \********************************************************************/ -/* - * The xaccGetAccountByName() is a convenience routine that - * is essentially identical to xaccGetPeerAccountFromName(), - * except that it accepts the handy transaction as root. - * - * The xaccGetAccountByFullName routine is similar, but uses - * full names using the given separator. - */ +/** The xaccGetAccountByName() is a convenience routine that + * is essentially identical to xaccGetPeerAccountFromName(), + * except that it accepts the handy transaction as root.*/ Account * xaccGetAccountByName (Transaction *trans, const char *name); +/** The xaccGetAccountByFullName routine is similar to xaccGetAccountByName, but uses + * full names using the given separator.*/ Account * xaccGetAccountByFullName (Transaction *trans, const char *name, const char separator); @@ -662,15 +697,13 @@ Account * xaccGetAccountByFullName (Transaction *trans, /** @name Transaction voiding */ /*@{*/ -/* - * xaccTransactionVoid voids a transaction. A void transaction +/** xaccTransactionVoid voids a transaction. A void transaction * has no values, is unaffected by reconciliation, and, by default * is not included in any queries. A voided transaction * should not be altered (and we'll try to make it so it can't be). * voiding is irreversible. Once voided, a transaction cannot be * un-voided. */ - void xaccTransVoid(Transaction *transaction, const char *reason); @@ -682,10 +715,18 @@ gnc_numeric xaccSplitVoidFormerAmount(const Split *split); gnc_numeric xaccSplitVoidFormerValue(const Split *split); Timespec xaccTransGetVoidTime(const Transaction *tr); -/*@}*/ +/**@}*/ -/* Parameter names */ +/** @name Split Parameter names + * Note, if you want to get the equivalent of "ACCT_MATCH_ALL" you + * need to create a search on the following parameter list: + * SPLIT->SPLIT_TRANS->TRANS_SPLITLIST->SPLIT_ACCOUNT_GUID. If you do + * this, you might want to use the ACCOUNT_MATCH_ALL_TYPE as the + * override so the gnome-search dialog displays the right type. + */ +/**@{*/ #define SPLIT_KVP "kvp" + #define SPLIT_DATE_RECONCILED "date-reconciled" #define SPLIT_BALANCE "balance" #define SPLIT_CLEARED_BALANCE "cleared-balance" @@ -702,13 +743,15 @@ Timespec xaccTransGetVoidTime(const Transaction *tr); #define SPLIT_LOT "lot" #define SPLIT_TRANS "trans" #define SPLIT_ACCOUNT "account" -#define SPLIT_ACCOUNT_GUID "account-guid" /* for guid_match_all */ - +#define SPLIT_ACCOUNT_GUID "account-guid" /**< for guid_match_all */ /* used for SORTING ONLY */ #define SPLIT_ACCT_FULLNAME "acct-fullname" #define SPLIT_CORR_ACCT_NAME "corr-acct-fullname" #define SPLIT_CORR_ACCT_CODE "corr-acct-code" +/**@}*/ +/** @name Transaction Parameter names */ +/**@{*/ #define TRANS_KVP "kvp" #define TRANS_NUM "num" #define TRANS_DESCRIPTION "desc" @@ -722,14 +765,9 @@ Timespec xaccTransGetVoidTime(const Transaction *tr); #define TRANS_VOID_REASON "void-reason" #define TRANS_VOID_TIME "void-time" #define TRANS_SPLITLIST "split-list" /* for guid_match_all */ - -/* Note, if you want to get the equivalent of "ACCT_MATCH_ALL" you - * need to create a search on the following parameter list: - * SPLIT->SPLIT_TRANS->TRANS_SPLITLIST->SPLIT_ACCOUNT_GUID. If you do - * this, you might want to use the ACCOUNT_MATCH_ALL_TYPE as the - * override so the gnome-search dialog displays the right type. - */ +/**@}*/ #define RECONCILED_MATCH_TYPE "reconciled-match" #endif /* XACC_TRANSACTION_H */ +/** @} */