Update docs.

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

src/doc/design/engine.texinfo

@@ -671,6 +671,18 @@ user input.
 Allocate, initialize, and return a new Split.
 @end deftypefun
 
+@deftypefun void xaccSplitDestroy (Split * @var{split})
+Update @var{split}'s parent Account and Transaction in a consistent
+manner, completely unlinking of @var{split} and freeing its memory. The
+goal of this routine is to perform the removal and destruction of the
+Split in an atomic fashion, with no chance of accidentally leaving the
+accounting structure out-of-balance or otherwise inconsistent.
+
+If the deletion of the Split leaves the Transaction with no Splits, then
+the Transaction will be marked for deletion, but will not be deleted
+until the @code{xaccTransCommitEdit()} routine is called.
+@end deftypefun
+
 @deftypefun {const GUID *} xaccSplitGetGUID (Split * @var{split})
 Return the GUID of @var{split}.
 @end deftypefun 
@@ -924,6 +936,50 @@ 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
+@code{xaccTransCommitEdit()} in which case the transaction memory will
+be freed, or by @code{xaccTransRollbackEdit()}, in which case all the
+original Splits are put back into place.
+@end deftypefun
+
+@deftypefun void xaccTransBeginEdit (Transaction * @var{trans}, gboolean @var{defer})
+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. If
+@var{defer} is true, then the automated re-balancing of all Splits in
+this transaction is deferred until the @code{xaccTransCommitEdit()}
+call. This allows multiple splits to be edited, quantities modified,
+with the whole system temporarily out of balance, up until the
+Commit call is made when double-entry is once again enforced.
+@end deftypefun
+
+@deftypefun void xaccTransCommitEdit (Transaction * @var{trans})
+This method indicates that the changes to @var{trans} 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 if @code{xaccTransDestroy()} was called on the Transaction.
+@end deftypefun
+
+@deftypefun void xaccTransRollbackEdit (Transaction * @var{trans})
+Rejects all changes made to @var{trans} and its Splits, and sets
+@var{trans} back to where it was before the @code{xaccTransBeginEdit()}
+call. This includes restoring any deleted Splits, removing any added
+Splits, and undoing the effects of @code{xaccTransDestroy()}, as well
+as restoring share quantities, memos, descriptions, etc.
+@end deftypefun
+
+@deftypefun gboolean xaccTransIsOpen (Transaction * @var{trans})
+Return @code{TRUE} if @var{trans} is open for editing. Otherwise, it
+returns @code{FALSE}.
+@end deftypefun
+
 @deftypefun {const GUID *} xaccTransGetGUID (Transaction * @var{trans})
 Return the GUID of @var{trans}.
 @end deftypefun 
@@ -988,6 +1044,9 @@ Return the number of Splits in @var{trans}.
 @node Transaction Setters,  , Transaction Getters, Transactions
 @subsection Transaction Setters
 
+Remember, before you modify a Transaction, you must open it for editing
+with @code{xaccTransBeginEdit}.
+
 @deftypefun void xaccTransSetDate (Transaction * @var{trans}, int @var{day}, int @var{mon}, int @var{year})
 Set the post date of @var{trans} with @var{day}, @var{month}, and @var{year}.
 @end deftypefun

src/engine/Transaction.h

@@ -93,26 +93,24 @@ void          xaccTransDestroy (Transaction *trans);
  *    this is not done, errors will result.  If the defer flag is set, 
  *    then the automated re-balancing of all splits in this transaction
  *    is deferred until the xaccTransCommitEdit() call. This allows 
- *    multiple splits to be edited, and prices fiddled with, and the whole
- *    system sent temporarily out of balance, up until the Commit
+ *    multiple splits to be edited, and quantities modified, and the
+ *    whole system temporarily out of balance, up until the Commit
  *    call is made when double-entry is once again enforced.
  *
- * The xaccTransCommitEdit() method should be used to indicate that 
- *    all of the manipulations on the transaction are complete, and
- *    that these should be made permanent.  Note that this routine
- *    may result in the deletion of the transaction, if the transaction 
- *    is "empty" (has no splits, or * has a single split in it whose 
- *    value is non-zero.)
+ * 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 prices, memo's descriptions, etc.
+ *    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.
- */
+ *    is open for editing. Otherwise, it returns false.  */
 void          xaccTransBeginEdit (Transaction *trans, gboolean defer);
 void          xaccTransCommitEdit (Transaction *trans);
 void          xaccTransRollbackEdit (Transaction *trans);
@@ -197,13 +195,10 @@ void          xaccTransAppendSplit (Transaction *trans, Split *split);
  *    leaving the accounting structure out-of-balance or otherwise
  *    inconsistent.
  *
- *    If the deletion of the split leaves the transaction "empty",
- *    then the transaction will be marked for deletion.  (It will
- *    not be deleted until the xaccTransCommitEdit() routine is called.)
- *    The transaction is considered "empty" if it has no splits in it, 
- *    or it has only one split left, and that split is not a price split
- *    (i.e. has a non-zero value).  Transactions with only one split in 
- *    them are valid if and only if the value of that split is zero.
+ *    If the deletion of the split leaves the transaction with no
+ *    splits, then the transaction will be marked for deletion. (It
+ *    will not be deleted until the xaccTransCommitEdit() routine is
+ *    called.)
  */
 void          xaccSplitDestroy (Split *split);