Be much more agressive in AccessCoin docs.

While the current implementation is pretty free, there is a lot
of possibility for this to blow up in our face with future changes,
especially as the backing map gets tweaked.

1 files changed, 7 insertions, 2 deletions

diff --git a/src/coins.h b/src/coins.h
index 4a0eaadc8..89613a61b 100644
--- a/src/coins.h
+++ b/src/coins.h
@@ -222,8 +222,13 @@ public:
 
     /**
      * Return a reference to Coin in the cache, or a pruned one if not found. This is
-     * more efficient than GetCoin. Modifications to other cache entries are
-     * allowed while accessing the returned pointer.
+     * more efficient than GetCoin.
+     *
+     * Generally, do not hold the reference returned for more than a short scope.
+     * While the current implementation allows for modifications to the contents
+     * of the cache while holding the reference, this behavior should not be relied
+     * on! To be safe, best to not hold the returned reference through any other
+     * calls to this cache.
      */
     const Coin& AccessCoin(const COutPoint &output) const;