docs: introduce doxygen comments for InstantSend (dashpay#4279)

* add comments

Signed-off-by: Pasta <[email protected]>

* Add doxygen comments for IS database handler

Signed-off-by: Pasta <[email protected]>

* Apply suggestions from code review

Co-authored-by: UdjinM6 <[email protected]>

* Apply suggestions from code review

Co-authored-by: UdjinM6 <[email protected]>

Co-authored-by: UdjinM6 <[email protected]>

Author: PastaPastaPasta

src/llmq/quorums_instantsend.h

@@ -58,24 +58,93 @@ class CInstantSendDb
 
     void Upgrade();
 
+    /**
+     * This method is called when an InstantSend Lock is processed and adds the lock to the database
+     * @param hash The hash of the InstantSend Lock
+     * @param islock The InstantSend Lock object itself
+     */
     void WriteNewInstantSendLock(const uint256& hash, const CInstantSendLock& islock);
+    /**
+     * This method removes a InstantSend Lock from the database and is called when a tx with an IS lock is confirmed and Chainlocked
+     * @param batch Object used to batch many calls together
+     * @param hash The hash of the InstantSend Lock
+     * @param islock The InstantSend Lock object itself
+     * @param keep_cache Should we still keep corresponding entries in the cache or not
+     */
     void RemoveInstantSendLock(CDBBatch& batch, const uint256& hash, CInstantSendLockPtr islock, bool keep_cache = true);
 
+    /**
+     * This method updates a DB entry for an InstantSend Lock from being not included in a block to being included in a block
+     * @param hash The hash of the InstantSend Lock
+     * @param nHeight The height that the transaction was included at
+     */
     void WriteInstantSendLockMined(const uint256& hash, int nHeight);
+    /**
+     * Marks an InstantSend Lock as archived.
+     * @param batch Object used to batch many calls together
+     * @param hash The hash of the InstantSend Lock
+     * @param nHeight The height that the transaction was included at
+     */
     static void WriteInstantSendLockArchived(CDBBatch& batch, const uint256& hash, int nHeight);
+    /**
+     * Archives and deletes all IS Locks which were mined into a block before nUntilHeight
+     * @param nUntilHeight Removes all IS Locks confirmed up until nUntilHeight
+     * @return returns an unordered_map of the hash of the IS Locks and a pointer object to the IS Locks for all IS Locks which were removed
+     */
     std::unordered_map<uint256, CInstantSendLockPtr> RemoveConfirmedInstantSendLocks(int nUntilHeight);
+    /**
+     * Removes IS Locks from the archive if the tx was confirmed 100 blocks before nUntilHeight
+     * @param nUntilHeight the height from which to base the remove of archive IS Locks
+     */
     void RemoveArchivedInstantSendLocks(int nUntilHeight);
     void WriteBlockInstantSendLocks(const std::shared_ptr<const CBlock>& pblock, const CBlockIndex* pindexConnected);
     void RemoveBlockInstantSendLocks(const std::shared_ptr<const CBlock>& pblock, const CBlockIndex* pindexDisconnected);
     bool KnownInstantSendLock(const uint256& islockHash) const;
+    /**
+     * Gets the number of IS Locks which have not been confirmed by a block
+     * @return size_t value of the number of IS Locks not confirmed by a block
+     */
     size_t GetInstantSendLockCount() const;
 
+    /**
+     * Gets a pointer to the IS Lock based on the hash
+     * @param hash The hash of the IS Lock
+     * @param use_cache Should we try using the cache first or not
+     * @return A Pointer object to the IS Lock, returns nullptr if it doesn't exist
+     */
     CInstantSendLockPtr GetInstantSendLockByHash(const uint256& hash, bool use_cache = true) const;
+    /**
+     * Gets an IS Lock hash based on the txid the IS Lock is for
+     * @param txid The txid which is being searched for
+     * @return Returns the hash the IS Lock of the specified txid, returns uint256() if it doesn't exist
+     */
     uint256 GetInstantSendLockHashByTxid(const uint256& txid) const;
+    /**
+     * Gets an IS Lock pointer from the txid given
+     * @param txid The txid for which the IS Lock Pointer is being returned
+     * @return Returns the IS Lock Pointer associated with the txid, returns nullptr if it doesn't exist
+     */
     CInstantSendLockPtr GetInstantSendLockByTxid(const uint256& txid) const;
+    /**
+     * Gets an IS Lock pointer from an input given
+     * @param outpoint Since all inputs are really just outpoints that are being spent
+     * @return IS Lock Pointer associated with that input.
+     */
     CInstantSendLockPtr GetInstantSendLockByInput(const COutPoint& outpoint) const;
 
+    /**
+     * Gets a vector of IS Lock hashes of the IS Locks which rely on or are children of the parent IS Lock
+     * @param parent The hash of the parent IS Lock
+     * @return Returns a vector of IS Lock hashes
+     */
     std::vector<uint256> GetInstantSendLocksByParent(const uint256& parent) const;
+    /**
+     * Called when a ChainLock invalidated a IS Lock, removes any chained/children IS Locks and the invalidated IS Lock
+     * @param islockHash IS Lock hash which has been invalidated
+     * @param txid Transaction id associated with the islockHash
+     * @param nHeight height of the block which recieved a chainlock and invalidated the IS Lock
+     * @return A vector of IS Lock hashes of all IS Locks removed
+     */
     std::vector<uint256> RemoveChainedInstantSendLocks(const uint256& islockHash, const uint256& txid, int nHeight);
 };