From 5b40d8868820265adb24fec097905e84edb85762 Mon Sep 17 00:00:00 2001 From: Michael Ford Date: Sun, 26 Oct 2014 15:03:12 +0800 Subject: [PATCH] Update comments in wallet to be doxygen compatible --- src/wallet.cpp | 76 ++++++++++++++++----------- src/wallet.h | 138 ++++++++++++++++++++++++++++--------------------- 2 files changed, 125 insertions(+), 89 deletions(-) diff --git a/src/wallet.cpp b/src/wallet.cpp index 3812c22fe..d392149db 100644 --- a/src/wallet.cpp +++ b/src/wallet.cpp @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #include "wallet.h" @@ -22,18 +22,23 @@ using namespace std; -// Settings +/** + * Settings + */ CFeeRate payTxFee(DEFAULT_TRANSACTION_FEE); unsigned int nTxConfirmTarget = 1; bool bSpendZeroConfChange = true; -/** Fees smaller than this (in satoshi) are considered zero fee (for transaction creation) */ -CFeeRate CWallet::minTxFee = CFeeRate(10000); // Override with -mintxfee +/** + * Fees smaller than this (in satoshi) are considered zero fee (for transaction creation) + * Override with -mintxfee + */ +CFeeRate CWallet::minTxFee = CFeeRate(10000); -////////////////////////////////////////////////////////////////////////////// -// -// mapWallet -// +/** @defgroup mapWallet + * + * @{ + */ struct CompareValueOnly { @@ -367,8 +372,10 @@ void CWallet::SyncMetaData(pair range) } } -// Outpoint is spent if any non-conflicted transaction -// spends it: +/** + * Outpoint is spent if any non-conflicted transaction + * spends it: + */ bool CWallet::IsSpent(const uint256& hash, unsigned int n) const { const COutPoint outpoint(hash, n); @@ -477,7 +484,7 @@ bool CWallet::EncryptWallet(const SecureString& strWalletPassphrase) { if (!pwalletdbEncryption->TxnCommit()) { delete pwalletdbEncryption; - // We now have keys encrypted in memory, but no on disk... + // We now have keys encrypted in memory, but not on disk... // die to avoid confusion and let the user reload their unencrypted wallet. assert(false); } @@ -667,9 +674,11 @@ bool CWallet::AddToWallet(const CWalletTx& wtxIn, bool fFromLoadWallet) return true; } -// Add a transaction to the wallet, or update it. -// pblock is optional, but should be provided if the transaction is known to be in a block. -// If fUpdate is true, existing transactions will be updated. +/** + * Add a transaction to the wallet, or update it. + * pblock is optional, but should be provided if the transaction is known to be in a block. + * If fUpdate is true, existing transactions will be updated. + */ bool CWallet::AddToWalletIfInvolvingMe(const CTransaction& tx, const CBlock* pblock, bool fUpdate) { { @@ -911,9 +920,11 @@ bool CWalletTx::WriteToDisk() return CWalletDB(pwallet->strWalletFile).WriteTx(GetHash(), *this); } -// Scan the block chain (starting in pindexStart) for transactions -// from or to us. If fUpdate is true, found transactions that already -// exist in the wallet will be updated. +/** + * Scan the block chain (starting in pindexStart) for transactions + * from or to us. If fUpdate is true, found transactions that already + * exist in the wallet will be updated. + */ int CWallet::ScanForWalletTransactions(CBlockIndex* pindexStart, bool fUpdate) { int ret = 0; @@ -1035,15 +1046,15 @@ void CWallet::ResendWalletTransactions() } } +/** @} */ // end of mapWallet - -////////////////////////////////////////////////////////////////////////////// -// -// Actions -// +/** @defgroup Actions + * + * @{ + */ CAmount CWallet::GetBalance() const @@ -1136,7 +1147,9 @@ CAmount CWallet::GetImmatureWatchOnlyBalance() const return nTotal; } -// populate vCoins with vector of available COutputs. +/** + * populate vCoins with vector of available COutputs. + */ void CWallet::AvailableCoins(vector& vCoins, bool fOnlyConfirmed, const CCoinControl *coinControl) const { vCoins.clear(); @@ -1194,7 +1207,7 @@ static void ApproximateBestSubset(vector& vWtx) setKeyPool.clear(); // Note: can't top-up keypool here, because wallet is locked. // User will be prompted to unlock wallet the next operation - // the requires a new key. + // that requires a new key. } } @@ -1736,10 +1751,10 @@ bool CWallet::SetDefaultKey(const CPubKey &vchPubKey) return true; } -// -// Mark old keypool keys as used, -// and generate all new keys -// +/** + * Mark old keypool keys as used, + * and generate all new keys + */ bool CWallet::NewKeyPool() { { @@ -2120,6 +2135,7 @@ void CWallet::ListLockedCoins(std::vector& vOutpts) } } +/** @} */ // end of Actions class CAffectedKeysVisitor : public boost::static_visitor { private: diff --git a/src/wallet.h b/src/wallet.h index 9b6895090..6ef830f22 100644 --- a/src/wallet.h +++ b/src/wallet.h @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto -// Copyright (c) 2009-2013 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Copyright (c) 2009-2014 The Bitcoin developers +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #ifndef BITCOIN_WALLET_H @@ -24,16 +24,18 @@ #include #include -// Settings +/** + * Settings + */ extern CFeeRate payTxFee; extern unsigned int nTxConfirmTarget; extern bool bSpendZeroConfChange; -// -paytxfee default +//! -paytxfee default static const CAmount DEFAULT_TRANSACTION_FEE = 0; -// -paytxfee will warn if called with a higher fee than this amount (in satoshis) per KB +//! -paytxfee will warn if called with a higher fee than this amount (in satoshis) per KB static const CAmount nHighTransactionFeeWarning = 0.01 * COIN; -// Largest (in bytes) free transaction we're willing to create +//! Largest (in bytes) free transaction we're willing to create static const unsigned int MAX_FREE_TRANSACTION_CREATE_SIZE = 1000; class CAccountingEntry; @@ -92,7 +94,8 @@ public: StringMap destdata; }; -/** A CWallet is an extension of a keystore, which also maintains a set of transactions and balances, +/** + * A CWallet is an extension of a keystore, which also maintains a set of transactions and balances, * and provides the ability to create new transactions. */ class CWallet : public CCryptoKeyStore, public CValidationInterface @@ -102,18 +105,20 @@ private: CWalletDB *pwalletdbEncryption; - // the current wallet version: clients below this version are not able to load the wallet + //! the current wallet version: clients below this version are not able to load the wallet int nWalletVersion; - // the maximum wallet format version: memory-only variable that specifies to what version this wallet may be upgraded + //! the maximum wallet format version: memory-only variable that specifies to what version this wallet may be upgraded int nWalletMaxVersion; int64_t nNextResend; int64_t nLastResend; - // Used to keep track of spent outpoints, and - // detect and report conflicts (double-spends or - // mutated transactions where the mutant gets mined). + /** + * Used to keep track of spent outpoints, and + * detect and report conflicts (double-spends or + * mutated transactions where the mutant gets mined). + */ typedef std::multimap TxSpends; TxSpends mapTxSpends; void AddToSpends(const COutPoint& outpoint, const uint256& wtxid); @@ -122,11 +127,13 @@ private: void SyncMetaData(std::pair); public: - /// Main wallet lock. - /// This lock protects all the fields added by CWallet - /// except for: - /// fFileBacked (immutable after instantiation) - /// strWalletFile (immutable after instantiation) + /* + * Main wallet lock. + * This lock protects all the fields added by CWallet + * except for: + * fFileBacked (immutable after instantiation) + * strWalletFile (immutable after instantiation) + */ mutable CCriticalSection cs_wallet; bool fFileBacked; @@ -186,7 +193,7 @@ public: const CWalletTx* GetWalletTx(const uint256& hash) const; - // check whether we are allowed to upgrade (or already support) to the named feature + //! check whether we are allowed to upgrade (or already support) to the named feature bool CanSupportFeature(enum WalletFeature wf) { AssertLockHeld(cs_wallet); return nWalletMaxVersion >= wf; } void AvailableCoins(std::vector& vCoins, bool fOnlyConfirmed=true, const CCoinControl *coinControl = NULL) const; @@ -200,38 +207,40 @@ public: void UnlockAllCoins(); void ListLockedCoins(std::vector& vOutpts); - // keystore implementation - // Generate a new key + /** + * keystore implementation + * Generate a new key + */ CPubKey GenerateNewKey(); - // Adds a key to the store, and saves it to disk. + //! Adds a key to the store, and saves it to disk. bool AddKeyPubKey(const CKey& key, const CPubKey &pubkey); - // Adds a key to the store, without saving it to disk (used by LoadWallet) + //! Adds a key to the store, without saving it to disk (used by LoadWallet) bool LoadKey(const CKey& key, const CPubKey &pubkey) { return CCryptoKeyStore::AddKeyPubKey(key, pubkey); } - // Load metadata (used by LoadWallet) + //! Load metadata (used by LoadWallet) bool LoadKeyMetadata(const CPubKey &pubkey, const CKeyMetadata &metadata); bool LoadMinVersion(int nVersion) { AssertLockHeld(cs_wallet); nWalletVersion = nVersion; nWalletMaxVersion = std::max(nWalletMaxVersion, nVersion); return true; } - // Adds an encrypted key to the store, and saves it to disk. + //! Adds an encrypted key to the store, and saves it to disk. bool AddCryptedKey(const CPubKey &vchPubKey, const std::vector &vchCryptedSecret); - // Adds an encrypted key to the store, without saving it to disk (used by LoadWallet) + //! Adds an encrypted key to the store, without saving it to disk (used by LoadWallet) bool LoadCryptedKey(const CPubKey &vchPubKey, const std::vector &vchCryptedSecret); bool AddCScript(const CScript& redeemScript); bool LoadCScript(const CScript& redeemScript); - /// Adds a destination data tuple to the store, and saves it to disk + //! Adds a destination data tuple to the store, and saves it to disk bool AddDestData(const CTxDestination &dest, const std::string &key, const std::string &value); - /// Erases a destination data tuple in the store and on disk + //! Erases a destination data tuple in the store and on disk bool EraseDestData(const CTxDestination &dest, const std::string &key); - /// Adds a destination data tuple to the store, without saving it to disk + //! Adds a destination data tuple to the store, without saving it to disk bool LoadDestData(const CTxDestination &dest, const std::string &key, const std::string &value); - /// Look up a destination data tuple in the store, return true if found false otherwise + //! Look up a destination data tuple in the store, return true if found false otherwise bool GetDestData(const CTxDestination &dest, const std::string &key, std::string *value) const; - // Adds a watch-only address to the store, and saves it to disk. + //! Adds a watch-only address to the store, and saves it to disk. bool AddWatchOnly(const CScript &dest); bool RemoveWatchOnly(const CScript &dest); - // Adds a watch-only address to the store, without saving it to disk (used by LoadWallet) + //! Adds a watch-only address to the store, without saving it to disk (used by LoadWallet) bool LoadWatchOnly(const CScript &dest); bool Unlock(const SecureString& strWalletPassphrase); @@ -240,17 +249,19 @@ public: void GetKeyBirthTimes(std::map &mapKeyBirth) const; - /** Increment the next transaction order id - @return next transaction order id + /** + * Increment the next transaction order id + * @return next transaction order id */ int64_t IncOrderPosNext(CWalletDB *pwalletdb = NULL); typedef std::pair TxPair; typedef std::multimap TxItems; - /** Get the wallet's activity log - @return multimap of ordered transactions and accounting entries - @warning Returned pointers are *only* valid within the scope of passed acentries + /** + * Get the wallet's activity log + * @return multimap of ordered transactions and accounting entries + * @warning Returned pointers are *only* valid within the scope of passed acentries */ TxItems OrderedTxItems(std::list& acentries, std::string strAccount = ""); @@ -318,7 +329,8 @@ public: return true; return false; } - bool IsFromMe(const CTransaction& tx) const // should probably be renamed to IsRelevantToMe + /** should probably be renamed to IsRelevantToMe */ + bool IsFromMe(const CTransaction& tx) const { return (GetDebit(tx, ISMINE_ALL) > 0); } @@ -384,19 +396,20 @@ public: bool SetDefaultKey(const CPubKey &vchPubKey); - // signify that a particular wallet feature is now used. this may change nWalletVersion and nWalletMaxVersion if those are lower + //! signify that a particular wallet feature is now used. this may change nWalletVersion and nWalletMaxVersion if those are lower bool SetMinVersion(enum WalletFeature, CWalletDB* pwalletdbIn = NULL, bool fExplicit = false); - // change which version we're allowed to upgrade to (note that this does not immediately imply upgrading to that format) + //! change which version we're allowed to upgrade to (note that this does not immediately imply upgrading to that format) bool SetMaxVersion(int nVersion); - // get the current wallet format (the oldest client version guaranteed to understand this wallet) + //! get the current wallet format (the oldest client version guaranteed to understand this wallet) int GetVersion() { LOCK(cs_wallet); return nWalletVersion; } - // Get wallet transactions that conflict with given transaction (spend same outputs) + //! Get wallet transactions that conflict with given transaction (spend same outputs) std::set GetConflicts(const uint256& txid) const; - /** Address book entry changed. + /** + * Address book entry changed. * @note called with lock cs_wallet held. */ boost::signals2::signal NotifyAddressBookChanged; - /** Wallet transaction added, removed or updated. + /** + * Wallet transaction added, removed or updated. * @note called with lock cs_wallet held. */ boost::signals2::signal=1 : this many blocks deep in the main chain + + /** + * Return depth of transaction in blockchain: + * -1 : not in blockchain, and not in memory pool (conflicted transaction) + * 0 : in memory pool, waiting to be included in a block + * >=1 : this many blocks deep in the main chain + */ int GetDepthInMainChain(const CBlockIndex* &pindexRet) const; int GetDepthInMainChain() const { const CBlockIndex *pindexRet; return GetDepthInMainChain(pindexRet); } bool IsInMainChain() const { const CBlockIndex *pindexRet; return GetDepthInMainChainINTERNAL(pindexRet) > 0; } @@ -526,7 +543,8 @@ public: bool AcceptToMemoryPool(bool fLimitFree=true, bool fRejectInsaneFee=true); }; -/** A transaction with a bunch of additional info that only the owner cares about. +/** + * A transaction with a bunch of additional info that only the owner cares about. * It includes any unrecorded transactions needed to link it back to the block chain. */ class CWalletTx : public CMerkleTx @@ -538,11 +556,11 @@ public: mapValue_t mapValue; std::vector > vOrderForm; unsigned int fTimeReceivedIsTxTime; - unsigned int nTimeReceived; // time received by this node + unsigned int nTimeReceived; //! time received by this node unsigned int nTimeSmart; char fFromMe; std::string strFromAccount; - int64_t nOrderPos; // position in ordered transaction list + int64_t nOrderPos; //! position in ordered transaction list // memory only mutable bool fDebitCached; @@ -634,7 +652,7 @@ public: } READWRITE(*(CMerkleTx*)this); - std::vector vUnused; // Used to be vtxPrev + std::vector vUnused; //! Used to be vtxPrev READWRITE(vUnused); READWRITE(mapValue); READWRITE(vOrderForm); @@ -659,7 +677,7 @@ public: mapValue.erase("timesmart"); } - // make sure balances are recalculated + //! make sure balances are recalculated void MarkDirty() { fCreditCached = false; @@ -678,7 +696,7 @@ public: MarkDirty(); } - // filter decides which addresses will count towards the debit + //! filter decides which addresses will count towards the debit CAmount GetDebit(const isminefilter& filter) const { if (vin.empty()) @@ -917,8 +935,8 @@ public: int64_t nTimeCreated; int64_t nTimeExpires; std::string strComment; - //// todo: add something to note what created it (user, getnewaddress, change) - //// maybe should have a map property map + //! todo: add something to note what created it (user, getnewaddress, change) + //! maybe should have a map property map CWalletKey(int64_t nExpires=0); @@ -940,7 +958,8 @@ public: -/** Account information. +/** + * Account information. * Stored in wallet with key "acc"+string account name. */ class CAccount @@ -970,7 +989,8 @@ public: -/** Internal transfers. +/** + * Internal transfers. * Database key is acentry. */ class CAccountingEntry @@ -982,7 +1002,7 @@ public: std::string strOtherAccount; std::string strComment; mapValue_t mapValue; - int64_t nOrderPos; // position in ordered transaction list + int64_t nOrderPos; //! position in ordered transaction list uint64_t nEntryNo; CAccountingEntry() @@ -1007,7 +1027,7 @@ public: inline void SerializationOp(Stream& s, Operation ser_action, int nType, int nVersion) { if (!(nType & SER_GETHASH)) READWRITE(nVersion); - // Note: strAccount is serialized as part of the key, not here. + //! Note: strAccount is serialized as part of the key, not here. READWRITE(nCreditDebit); READWRITE(nTime); READWRITE(LIMITED_STRING(strOtherAccount, 65536));