2001-05-16 Dave Peticolas <dave@krondo.com>

* src/doc/design/gnucash-design.texinfo: update docs

	* src/doc/design/engine.texinfo: update docs

	* src/engine/Account.c (xaccCloneAccountSimple): remove
	redundant initialization
	(xaccAccountGetSlots): handle NULL

	* src/engine/Account.h: fix docs

	* src/engine/AccountP.h: fix spelling errors in comments


git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@4228 57a11ea4-9604-0410-9ed3-97b8803252fd

ChangeLog

@@ -1,3 +1,17 @@
+2001-05-16  Dave Peticolas  <dave@krondo.com>
+
+	* src/doc/design/gnucash-design.texinfo: update docs
+
+	* src/doc/design/engine.texinfo: update docs
+
+	* src/engine/Account.c (xaccCloneAccountSimple): remove
+	redundant initialization
+	(xaccAccountGetSlots): handle NULL
+
+	* src/engine/Account.h: fix docs
+
+	* src/engine/AccountP.h: fix spelling errors in comments
+
 2001-05-16  Robert Graham Merkel  <rgmerk@mira.net>
 
 	* src/scm/html-utilities.scm ((gnc:html-make-empty-data-warning)): 
@@ -123,12 +137,13 @@
 
 2001-05-15  Robert Graham Merkel  <rgmerk@mira.net>
 
-	* doc/sgml/C/xacc-reports.sgml, xacc-about.sgml, xacc-dateinput.sgml, 
+	* doc/sgml/C/xacc-reports.sgml, xacc-about.sgml,
-	xacc-account-summary.sgml, xacc-balancesheet.sgml, xacc-common-report-options.sgml
+	xacc-dateinput.sgml, xacc-account-summary.sgml,
+	xacc-balancesheet.sgml, xacc-common-report-options.sgml
 	xacc-mainwin.sgml: update documentation for new features.
 
-	* doc/sgml/C/xacc-asset-liability-barcharts.sgml: new file.  Placeholder
+	* doc/sgml/C/xacc-asset-liability-barcharts.sgml: new file.
-	at this stage.
+	Placeholder at this stage.
 
 	* doc/sgml/C/xacc-asset-liability-piecharts.sgml, xacc-gnome-mdi.sgml,
 	xacc-income-expense-barcharts.sgml, xacc-income-expense-piecharts.sgml,

src/doc/design/engine.texinfo

@@ -258,7 +258,7 @@ directly. Example:
 
   account = < something to get an Account pointer >
 
-  saved_guid = *xaccAccountGetGuid(account);
+  saved_guid = *xaccAccountGetGUID(account);
 
   ...
 
@@ -1537,12 +1537,6 @@ for editing.
 Allocate, initialize, and return a new Transaction.
 @end deftypefun
 
-@deftypefun void xaccTransAppendSplit (Transaction * @var{trans}, Split * @var{split})
-Append @var{split} to the collection of Splits in @var{trans}. If the
-Split is already a part of another Transaction, it will be removed from
-that Transaction first.
-@end deftypefun
-
 @deftypefun void xaccTransDestroy (Transaction * {trans})
 Remove all of the Splits from each of their accounts and free the memory
 associated with them. This routine must be followed by either an
@@ -1551,6 +1545,12 @@ be freed, or by @code{xaccTransRollbackEdit()}, in which case all the
 original Splits are put back into place.
 @end deftypefun
 
+@deftypefun void xaccTransAppendSplit (Transaction * @var{trans}, Split * @var{split})
+Append @var{split} to the collection of Splits in @var{trans}. If the
+Split is already a part of another Transaction, it will be removed from
+that Transaction first.
+@end deftypefun
+
 @deftypefun void xaccTransBeginEdit (Transaction * @var{trans})
 This method must be called before any changes are made to @var{trans} or
 any of its component Splits. If this is not done, errors will result.
@@ -1694,9 +1694,19 @@ contain the following pieces of information:
 The list of debits and credits which apply to the Account. The sum of
 all debits and credits is the account balance.
 
+@item A type
+An integer code identifying the type of account. The Account type
+determines whether the Account holds shares valued in a currency
+or not. It is also used by the GUI and reporting system to determine
+how debits & credits to the Account should be treated and displayed.
+
 @item A name
 The name of the Account.
 
+@item An account code
+A string that is intended to hold a unique user-selected identifier
+for the account. However, uniqueness of this field is not enforced.
+
 @item A description
 A textual description of the Account.
 
@@ -1704,6 +1714,10 @@ A textual description of the Account.
 The commodity that Splits in the account are valued in, i.e., the
 denomination of the 'value' member of Splits in the account.
 
+@item A curreny SCU
+The SCU is the smallest convertible unit that the currency is
+traded in. This value overrides the default SCU of the currency.
+
 @item A security
 For Accounts which may contain shares (such as stock accounts),
 the denomination of the 'share quantity' member of Splits in
@@ -1711,10 +1725,135 @@ the accounts. For accounts which do not contain shares, the
 security is blank, and the share quantities are denominated
 in the Account currency.
 
+@item A security SCU
+Analogous to the currency SCU, but for the security.
+
+@item A parent and child Account Group.
+The parent and child of an Account are Account Groups
+(@pxref{Account Groups}). Account Groups are used to
+connect Accounts together into an Account hierarchy.
+If the parent Account Group is not present, the Account
+is at the top level of the hierarchy. If the child
+Account Group is not present, the Account has no
+children.
+
 @end table
 
 In addition to the above, Accounts contain a key-value pair frame.
 
+@menu
+* Account Types::               
+* General Account API::         
+@end menu
+
+
+@node Account Types, General Account API, Accounts, Accounts
+@subsection Account Types
+@tindex GNCAccountType
+
+Account Types are defined by the @code{GNCAccountType} enumeration.
+Possible values are:
+
+  @table @code
+
+  @item BAD_TYPE, NO_TYPE
+  Both of these values indicate an illegal Account type.
+
+  @item BANK
+  Denotes a savings or checking account held at a bank.
+  Such an account is often interest bearing.
+
+  @item CASH
+  Denotes a shoe-box or pillowcase stuffed with cash. In other
+  words, actual currency held by the user.
+
+  @item CREDIT
+  Denotes credit card accounts.
+
+  @item ASSET
+  Denotes a generic asset account.
+
+
+  @item LIABILITY
+  Denotes a generic liability account.
+
+  @item STOCK
+  A stock account containing stock shares.
+
+  @item MUTUAL
+  A mutual fund account containing fund shares.
+
+  @item CURRENCY
+  Denotes a currency trading account. In many ways, a currency trading
+  account is like a stock trading account, where both quantities
+  and prices are set. However, generally both currency and security
+  are national currencies.
+
+  @item INCOME
+  Denotes an income account. The GnuCash financial model does not
+  use 'categories'. Actual accounts are used instead.
+
+  @item EXPENSE
+  Denotes an expense account.
+
+  @item EQUITY = 10,
+  Denotes an equity account.
+
+  @end table
+
+
+@node General Account API,  , Account Types, Accounts
+@subsection General Account API
+
+@deftypefun {Account *} xaccMallocAccount (void)
+Allocate and initialize an Account. The account must be
+destroyed by calling @code{xaccAccountBeginEdit} followed
+by @code{xaccAccountDestroy}.
+@end deftypefun
+
+@deftypefun void xaccAccountDestroy (Account * @var{account})
+Destroys @var{account} and frees all memory associated with
+it. This routine will also destroy the Account's children.
+You must call @code{xaccAccountBeginEdit} before calling
+this function.
+@end deftypefun
+
+@deftypefun void xaccAccountBeginEdit (Account * @var{account})
+This routine, together with @code{xaccAccountCommitEdit},
+provide a two-phase-commit wrapper for account updates
+much in the same way as @var{xaccTransBeginEdit} and
+@var{xaccTransCommitEdit} do for Transactions.
+@end deftypefun
+
+@deftypefun void xaccAccountCommitEdit (Account * @var{account})
+The counterpart to @var{xaccAccountBeginEdit}.
+@end deftypefun
+
+@deftypefun {Account *} xaccCloneAccountSimple(const Account * @var{from})
+Return a 'copy' of @var{from} that is identical in the type, name, code,
+description, kvp data, and currency. All other fields are the same as an
+account returned by @code{xaccMallocAccount}.
+@end deftypefun
+
+@deftypefun {const GUID *} xaccAccountGetGUID (Account * @var{account})
+Return the globally unique id associated with @var{account}.
+@end deftypefun
+
+@deftypefun {Account *} xaccAccountLookup (const GUID * @var{guid})
+Return the Account associated with @var{guid}, or NULL if there is
+no such Account.
+@end deftypefun
+
+@deftypefun {kvp_frame *} xaccAccountGetSlots (Account * @var{account})
+Return the @code{kvp_frame} associated with @var{account}. User code
+may modify this @code{kvp_frame}, but must not destroy it.
+@end deftypefun
+
+@deftypefun void xaccAccountSetSlots_nc (Account * @var{account}, kvp_frame * @var{frame})
+Set the @code{kvp_frame} associated wih @var{account}. After the call,
+@var{frame} is owned by @var{account}, so don't destroy it.
+@end deftypefun
+
 
 @node Account Groups, GNCBooks, Accounts, Engine
 @section Account Groups

src/doc/design/gnucash-design.texinfo

@@ -130,12 +130,17 @@ Splits
 * Split Getters::               
 * Split Setters::               
 
-The Transaction Edit Cycle
+Transactions
 
 * General Transaction API::     
 * Transaction Getters::         
 * Transaction Setters::         
 
+Accounts
+
+* Account Types::               
+* General Account API::         
+
 GNCBooks
 
 * GNCBook API::                 

src/engine/Account.c

@@ -141,7 +141,6 @@ xaccCloneAccountSimple(const Account *from)
     Account *ret;
 
     ret = xaccMallocAccount();
-    xaccInitAccount(ret);
 
     ret->type = from->type;
 
@@ -476,6 +475,7 @@ xaccAccountBringUpToDate(Account *acc)
 
 kvp_frame * 
 xaccAccountGetSlots(Account * account) {
+  if (!account) return NULL;
   return(account->kvp_data);
 }
 

src/engine/Account.h

@@ -81,16 +81,13 @@ typedef enum
   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 quantities
+   * account is like a stock trading account, where both values
-   * and prices are set.
+   * and share quantities are set.
    */
 
   INCOME = 8,
   EXPENSE = 9,
-  /* Income and expense accounts are used to denote income and expenses.
+  /* Income and expense accounts are used to denote income and expenses. */
-   * Thus, when data in these accountsare displayed, the sign of the
-   * splits (entries) must be reversed.
-   */ 
 
   EQUITY = 10,
   /* Equity account is used to balance the balance sheet. */
@@ -122,14 +119,14 @@ gboolean xaccAccountEqual(Account *a, Account* b, gboolean check_guids);
 /* 
  * The xaccAccountBeginEdit() and xaccAccountCommitEdit() subroutines
  * provide a two-phase-commit wrapper for account updates. 
- * They are incompletely implemented ....
+ * They are incompletely implemented.
  *
  * 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.
  */
-Account     *xaccMallocAccount (void);
+Account    * xaccMallocAccount (void);
-Account * xaccCloneAccountSimple(const Account *from);
+Account    * xaccCloneAccountSimple(const Account *from);
 void         xaccAccountBeginEdit (Account *account);
 void         xaccAccountCommitEdit (Account *account);
 void         xaccAccountDestroy (Account *account);
@@ -140,8 +137,6 @@ void xaccAccountSetSlots_nc(Account *account, kvp_frame *frame);
 /*
  * The xaccAccountGetGUID() subroutine will return the
  *    globally unique id associated with that account.
- *    User code should use this id to reference accounts
- *    and *not* the integer account id below.
  *
  * The xaccAccountLookup() subroutine will return the
  *    account associated with the given id, or NULL
@@ -222,7 +217,7 @@ void xaccAccountSetCommodity (Account *account, gnc_commodity *comm);
  * The future API will associate only one thing with an account:
  * the 'commodity'.  Use xaccAccountGetCommodity() to fetch it.
  */
-/* these two funcs take control of thier gnc_commodity args.  Don't free */
+/* these two funcs take control of their gnc_commodity args. Don't free */
 void xaccAccountSetCurrency (Account *account, gnc_commodity *currency);
 void xaccAccountSetSecurity (Account *account, gnc_commodity *security);
 void xaccAccountSetCurrencySCU (Account *account, int frac);

src/engine/AccountP.h

@@ -57,23 +57,23 @@ struct _account {
   /* public data, describes account */
   GUID      guid;          /* globally unique account id */
 
-  /* The accountName is an arbitrary string assinged by the user. 
+  /* The accountName is an arbitrary string assigned by the user. 
    * It is intended to a short, 5 to 30 character long string that
-   * is displayed by the GUI as the account mnomenic. 
+   * is displayed by the GUI as the account mnemonic. 
    */
   char     *accountName;
 
-  /* The accountCode is an arbitary string assigned by the user.
+  /* The accountCode is an arbitrary string assigned by the user.
    * It is intended to be reporting code that is a synonym for the 
-   * accountName. Typically, it will be a numeric value tht follows 
+   * accountName. Typically, it will be a numeric value that follows 
    * the numbering assignments commonly used by accountants, such 
    * as 100, 200 or 600 for top-level * accounts, and 101, 102..  etc.
    * for detail accounts.
    */
   char     *accountCode;
 
-  /* The description is an arbitraary string assigned by the user. 
+  /* The description is an arbitrary string assigned by the user. 
-   * It is intended to be a longer, 1-5 sentance description of what
+   * It is intended to be a longer, 1-5 sentence description of what
    * this account is all about.
    */
   char     *description;