gnucash maint: Warn against using xaccTransGetSplit for iteration.

[John Ralls]

Updated	 via  https://github.com/Gnucash/gnucash/commit/a93f3c19 (commit)
	from  https://github.com/Gnucash/gnucash/commit/e9a1d491 (commit)



commit a93f3c198d16306618a0f4fce764a4f8ab104cc7
Author: John Ralls <jralls at ceridwen.us>
Date:   Mon Jul 20 13:07:05 2020 -0700

    Warn against using xaccTransGetSplit for iteration.
    
    Instead of encouraging it.

diff --git a/libgnucash/engine/Transaction.h b/libgnucash/engine/Transaction.h
index 18efbf340..a169650c2 100644
--- a/libgnucash/engine/Transaction.h
+++ b/libgnucash/engine/Transaction.h
@@ -360,14 +360,16 @@ gboolean      xaccTransGetIsClosingTxn (const Transaction *trans);
 */
 #define xaccTransAppendSplit(t, s) xaccSplitSetParent((s), (t))
 
-/** The xaccTransGetSplit() method returns a pointer to each of the
-    splits in this transaction.
+/** Return a pointer to the indexed split in this transaction's split list.
+
+    Note that the split list is a linked list and that indexed access is
+    O(N). Do not use this method for iteration.
     @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);
+    (number_of__splits-1).
+    @return A Split* or NULL if i is out of range.
+*/
+Split* xaccTransGetSplit (const Transaction *trans, int i);
 
 /** Inverse of xaccTransGetSplit() */
 int xaccTransGetSplitIndex(const Transaction *trans, const Split *split);



Summary of changes:
 libgnucash/engine/Transaction.h | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)