Clarify hiding internal refreshes from user-facing balance

1 files changed, 7 insertions, 3 deletions

diff --git a/taler-wallet.rst b/taler-wallet.rst
index 1c27d827..7d0e98a6 100644
--- a/taler-wallet.rst
+++ b/taler-wallet.rst
@@ -102,21 +102,25 @@ Balances are the amounts of digital cash held by the wallet.
     interface Balance {
       currency?: string;
 
-      // the total Amount that is currently available to be spent
+      // The total Amount that is currently available to be spent
+      // excluding amounts tied up in ongoing refresh operations. These are hidden from the user.
+      // If the user tries to spend coins locked up this way,
+      // the wallet will give an error message different from "insufficient balance".
       available: Amount;
 
       // the total incoming amount that will be added to the available balance
-      // when all pending transactions succeed
+      // when all pending transactions succeed (excluding internal refreshes)
       pendingIncoming: Amount;
 
       // the total outgoing amount that will be subtracted from the available balance
-      // when all pending transactions succeed
+      // when all pending transactions succeed (excluding internal refreshes)
       pendingOutgoing: Amount;
 
       // true if the balance has pending transactions
       hasPendingTransactions: boolean;
 
       // true if the balance requires user-interaction, e.g. accepting a tip
+      // (DEV: can be left out of a first implementation)
       requiresUserInput: boolean;
     }