more fields, documentation, etc.

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

src/engine/AccInfo.h

@@ -37,19 +37,51 @@
  * Note: the actual values of these are *very* important, 
  * as it is the values, not the enums, that are stored 
  * in the file format! 
+ * hack alert  ... note that this is a bug that should be fixed ...
+ */
+
+/*
+ * The account types are used to determine how the transaction data
+ * in the account is displayed.  
  */
 enum 
 {
   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,
-  CREDIT = 3,          /* credit card */
   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.
+   */
+
   INCOME = 7,
   EXPENSE = 8,
+  /* 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 = 9,
+  /* Equity account is used to balance the balance sheet. */
 
   /* bank account types */
   CHECKING = 10,
@@ -57,6 +89,12 @@ enum
   MONEYMRKT = 12,
   CREDITLINE = 13,     /* line of credit */
 
+  /* CURRENCY = 20, */
+  /* 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 and prices are set.
+   */
+
   NUM_ACCOUNT_TYPES = 14
 };
 

src/engine/Account.c

@@ -68,15 +68,19 @@ xaccInitAccount (Account * acc)
 
   acc->balance  = 0.0;
   acc->cleared_balance = 0.0;
+  acc->reconciled_balance = 0.0;
   acc->running_balance  = 0.0;
   acc->running_cleared_balance = 0.0;
+  acc->running_reconciled_balance = 0.0;
 
   acc->flags = 0;
   acc->type  = -1;
   
   acc->accountName = NULL;
+  acc->accountCode = NULL;
   acc->description = NULL;
   acc->notes       = NULL;
+  acc->currency    = NULL;
   
   acc->numSplits   = 0;
   acc->splits      = (Split **) _malloc (sizeof (Split *));
@@ -111,9 +115,11 @@ xaccFreeAccount( Account *acc )
   /* recursively free children */
   xaccFreeAccountGroup (acc->children);
 
-  free(acc->accountName);
-  free(acc->description);
-  free(acc->notes);
+  if (acc->accountName) free (acc->accountName);
+  if (acc->accountCode) free (acc->accountCode);
+  if (acc->description) free (acc->description);
+  if (acc->notes) free (acc->notes);
+  if (acc->currency) free (acc->currency);
   
   /* any split pointing at this account needs to be unmarked */
   i=0;
@@ -145,6 +151,7 @@ xaccFreeAccount( Account *acc )
 
   acc->balance  = 0.0;
   acc->cleared_balance = 0.0;
+  acc->reconciled_balance = 0.0;
 
   acc->flags = 0;
   acc->type  = -1;
@@ -152,6 +159,7 @@ xaccFreeAccount( Account *acc )
   acc->accountName = NULL;
   acc->description = NULL;
   acc->notes       = NULL;
+  acc->currency    = NULL;
   
   acc->changed     = 0;
   acc->open        = 0;

src/engine/AccountP.h

@@ -50,14 +50,60 @@
 struct _account {
   /* public data, describes account */
 
+  /* The accountName is an arbitrary string assinged 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. 
+   */
+  char     *accountName;
+
+  /* The accountCode is an arbitary 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 
+   * 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. 
+   * It is intended to be a longer, 1-5 sentance description of what
+   * this account is all about.
+   */
+  char     *description;
+
+  /* The notes field is an arbitrary string assigned by the user.
+   * It is intended to hold long, free-form and/or MIME-format 
+   * arbitrary additional data about the account.
+   */
+  char     *notes;
+
+  /* The type field is the account type, picked from the enumerated 
+   * list that includes BANK, STOCK, CREDIT, INCOME, etc.  It's
+   * intended use is to be a hint to the GUI as to how to display   
+   * and format the transaction data.
+   */
+  short     type;
+
+  /* The currency field denotes the default currency in which all
+   * splits in this account are denominated.  It's value *MUST*
+   * be a three-letter ISO currency code.  Currency trading accounts
+   * are created by creating two accounts, each with a different
+   * default currency, and then having transactions with one split in one
+   * currency account, and another split in the other currency account.
+   */
+  char    *currency;
+
+  /* The parent and children pointers are used to implement an account
+   * heirarchy, of accounts that have sub-accounts ("detail accounts").
+   */
   AccountGroup *parent;    /* back-pointer to parent */
   AccountGroup *children;  /* pointer to sub-accounts */
-  int       id;                     /* unique account id, internally assigned */
+
+  /* The id number is internally assigned by the engine, and is used for 
+   * various housekeeping operations by the engine.
+   */
+  int       id;            /* unique account id, internally assigned */
   char      flags;
-  short     type;
-  char     *accountName;
-  char     *description;
-  char     *notes;
 
   /* protected data, cached parameters */
   double balance;