Merge #18030: doc: Coin::IsSpent() can also mean never existed

1404c574037da331c233317618b9b90d3329ed33 [doc] Coin: explain that IsSpent() can also mean never existed (Sjors Provoost)

Pull request description:

  This can be especially confusing where `AccessCoin()` is used with logic like this:

  ```c++
      while (iter.n < MAX_OUTPUTS_PER_BLOCK) {
          const Coin& alternate = view.AccessCoin(iter);
          if (!alternate.IsSpent()) return alternate;
  ```

ACKs for top commit:
  practicalswift:
    ACK 1404c574037da331c233317618b9b90d3329ed33
  MarcoFalke:
    ACK 1404c574037da331c233317618b9b90d3329ed33
  jnewbery:
    utACK 1404c574037da331c233317618b9b90d3329ed33

Tree-SHA512: 418618dd7e08bd5cc8360e3501d0f57e34100e5101ad3b8e0a819923fa860f44c7f2fada0f8447a1af3c2601fd72bfe619b91ff2f26f7133ceaeb0c98b017b12

1 files changed, 3 insertions, 0 deletions

diff --git a/src/coins.h b/src/coins.h
index feb441fd6a..5a6f73652b 100644
--- a/src/coins.h
+++ b/src/coins.h
@@ -75,6 +75,9 @@ public:
         ::Unserialize(s, Using<TxOutCompression>(out));
     }
 
+    /** Either this coin never existed (see e.g. coinEmpty in coins.cpp), or it
+      * did exist and has been spent.
+      */
     bool IsSpent() const {
         return out.IsNull();
     }