clirification, additional docs,

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

src/engine/AccInfo.h

@@ -106,10 +106,10 @@ extern char *account_type_name [NUM_ACCOUNT_TYPES];
 struct _BankAcct 
 {
   char * bankid;       /* routing and transit number */
-  char * branchid;     /* bank identifier for international banks */  
+  char * branchid;     /* branch office bank identifier */  
   char * acctid;       /* account number */
   char * accttype;     /* account type */
-  char * acctkey;      /* checksum for international banks */
+  char * acctkey;      /* checksum key */
   int acctype;         /* account type.  Must be one of 
                         * CHECKING = 10;
                         * SAVINGS = 11;

src/engine/AccountP.h

@@ -72,8 +72,11 @@ struct _account {
   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 
+   * It is intended to hold long, free-form arbitrary additional 
-   * arbitrary additional data about the account.
+   * data about the account. Machine-readable data *must* be 
+   * structured using standard mime-type techniques.  For example,
+   * image data would be Base64 encoded, and lists of key-value
+   * pairs would be URL-encoded.
    */
   char     *notes;
 

src/engine/Transaction.c

@@ -77,6 +77,7 @@ xaccInitSplit( Split * split )
   
   split->action      = strdup("");
   split->memo        = strdup("");
+  split->docref      = strdup("");
   split->reconciled  = NREC;
   split->damount     = 0.0;
   split->share_price = 1.0;
@@ -111,11 +112,14 @@ xaccFreeSplit( Split *split )
   {
   if (!split) return;
 
-  free(split->memo);
+  if (split->memo) free (split->memo);
-  free(split->action);
+  if (split->action) free (split->action);
+  if (split->docref) free (split->docref);
 
   /* just in case someone looks up freed memory ... */
   split->memo        = 0x0;
+  split->action      = 0x0;
+  split->docref      = 0x0;
   split->reconciled  = NREC;
   split->damount     = 0.0;
   split->share_price = 1.0;
@@ -248,6 +252,7 @@ xaccInitTransaction( Transaction * trans )
   /* fill in some sane defaults */
   trans->num         = strdup("");
   trans->description = strdup("");
+  trans->docref      = strdup("");
 
   trans->splits    = (Split **) _malloc (3* sizeof (Split *));
 
@@ -302,12 +307,14 @@ xaccFreeTransaction( Transaction *trans )
   _free (trans->splits);
 
   /* free up transaction strings */
-  free(trans->num);
+  if (trans->num) free (trans->num);
-  free(trans->description);
+  if (trans->description) free (trans->description);
+  if (trans->docref) free (trans->docref);
 
   /* just in case someone looks up freed memory ... */
   trans->num         = 0x0;
   trans->description = 0x0;
+  trans->docref      = 0x0;
 
   trans->date_entered.tv_sec = 0;
   trans->date_entered.tv_nsec = 0;

src/engine/TransactionP.h

@@ -65,6 +65,8 @@
  * one account, and pieces of it show up as debits (or credits) in other
  * accounts.  Thus, a single credit-card transaction might be split
  * between "dining", "tips" and "taxes" categories.
+ *
+ * A "split" is more commonly refered to as a "entry" in a "transaction".
  */
 
 typedef struct timespec Timespec;
@@ -73,14 +75,37 @@ struct _split
 {
   Account *acc;              /* back-pointer to debited/credited account  */
   Transaction *parent;       /* parent of split                           */
+
+  /* The memo field is an arbitrary user-assiged value. 
+   * It is intended to hold a short (zero to forty cahracter) string 
+   * that is displayed by the GUI along with this split. 
+   */
   char  * memo;
+
+  /* The action field is an arbitrary user-assigned value.
+   * It is meant to be a very short (oen to ten cahracter) string that
+   * signifies the "type" of this split, such as e.g. Buy, Sell, Div,
+   * Withdraw, Deposit, ATM, Check, etc. The idea is that this field
+   * can be used to create custom reports or graphs of data.
+   */ 
   char  * action;            /* Buy, Sell, Div, etc.                      */
+
+  /* The docref field is a hook for arbitrary additional user-assigned
+   * data, such as invoice numbers, clearing/posting reference numbers, 
+   * supporting document references, etc. This additional data should
+   * be encoded in a machine-readable format, e.g. a mime-type encapsulated
+   * form, which any key-value pairs being URL-encoded.
+   */
+  char * docref;
+
+  /* The reconciled field ...
+   */
   char    reconciled;
+  Timespec date_reconciled;  /* date split was reconciled                 */
+
   double  damount;           /* num-shares; if > 0.0, deposit, else paymt */
   double  share_price;       /* the share price, ==1.0 for bank account   */
 
-  Timespec date_reconciled;  /* date split was reconciled                 */
-
   /* The various "balances" are the sum of all of the values of 
    * all the splits in the account, up to and including this split.
    * These belances apply to a sorting order by date posted
@@ -100,9 +125,26 @@ struct _transaction
 {
   Timespec date_entered;     /* date register entry was made              */
   Timespec date_posted;      /* date transaction was posted at bank       */
-  char  * num;               /* transaction id                            */
+
+  /* The num field is a arbitrary user-assigned field.  
+   * It is intended to store a short id number, typically the check number,
+   * deposit number, invoice number or other tracking number
+   */
+  char  * num;  
+
+  /* The description field is an arbitrary user-assigned value. 
+   * It is meant to be a short descriptive phrase.
+   */
   char  * description;        
 
+  /* The docref field is a hook for arbitrary additional user-assigned
+   * data, such as invoice numbers, clearing/posting reference numbers, 
+   * supporting document references, etc. This additional data should
+   * be encoded in a machine-readable format, e.g. a mime-type encapsulated
+   * form, which any key-value pairs being URL-encoded.
+   */
+  char * docref;
+
   Split   **splits;          /* list of splits, null terminated           */
 
   char    write_flag;        /* used only during file IO                  */