[docs] Add doxygen comment for CReserveKey

jnewbery · jnewbery · commit f1a77b0c5176 · 2019-05-01T14:53:36.000-04:00
diff --git a/src/wallet/wallet.h b/src/wallet/wallet.h
@@ -228,16 +228,35 @@ class CKeyPool
     }
 };
 
-/** A key allocated from the key pool. */
+/** A wrapper to reserve a key from a wallet keypool
+ *
+ * CReserveKey is used to reserve a key from the keypool. It is passed around
+ * during the CreateTransaction/CommitTransaction procedure.
+ *
+ * Instantiating a CReserveKey does not reserve a keypool key. To do so,
+ * GetReservedKey() needs to be called on the object. Once a key has been
+ * reserved, call KeepKey() on the CReserveKey object to make sure it is not
+ * returned to the keypool. Call ReturnKey() to return the key to the keypool
+ * so it can be re-used (for example, if the key was used in a new transaction
+ * and that transaction was not completed and needed to be aborted).
+ *
+ * If a key is reserved and KeepKey() is not called, then the key will be
+ * returned to the keypool when the CReserveObject goes out of scope.
+ */
 class CReserveKey
 {
 protected:
+    //! The wallet to reserve the keypool key from
     CWallet* pwallet;
+    //! The index of the key in the keypool
     int64_t nIndex{-1};
+    //! The public key
     CPubKey vchPubKey;
+    //! Whether this is from the internal (change output) keypool
     bool fInternal{false};
 
 public:
+    //! Construct a CReserveKey object. This does NOT reserve a key from the keypool yet
     explicit CReserveKey(CWallet* pwalletIn)
     {
         pwallet = pwalletIn;
@@ -246,13 +265,17 @@ class CReserveKey
     CReserveKey(const CReserveKey&) = delete;
     CReserveKey& operator=(const CReserveKey&) = delete;
 
+    //! Destructor. If a key has been reserved and not KeepKey'ed, it will be returned to the keypool
     ~CReserveKey()
     {
         ReturnKey();
     }
 
-    void ReturnKey();
+    //! Reserve a key from the keypool
     bool GetReservedKey(CPubKey &pubkey, bool internal = false);
+    //! Return a key to the keypool
+    void ReturnKey();
+    //! Keep the key. Do not return it to the keypool when this object goes out of scope
     void KeepKey();
 };
 
