From fa94b9d5623cfd16aa594c28432f25a17b0efb0e Mon Sep 17 00:00:00 2001 From: Michael Ford Date: Fri, 31 Oct 2014 08:43:19 +0800 Subject: Convert remaining comments in /src to doxygen format - Update comments in checkpoints to be doxygen compatible - Update comments in checkqueue to be doxygen compatible - Update coins to be doxygen compatible - Fix comment typo in crypter.h - Update licenses/copyright dates Closes #5325 #5184 #5183 #5182 --- src/coins.h | 115 ++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 65 insertions(+), 50 deletions(-) (limited to 'src/coins.h') diff --git a/src/coins.h b/src/coins.h index ee9051562b..dbe3f8bd31 100644 --- a/src/coins.h +++ b/src/coins.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_COINS_H @@ -17,7 +17,8 @@ #include #include -/** pruned version of CTransaction: only retains metadata and unspent transaction outputs +/** + * Pruned version of CTransaction: only retains metadata and unspent transaction outputs * * Serialized format: * - VARINT(nVersion) @@ -71,17 +72,17 @@ class CCoins { public: - // whether transaction is a coinbase + //! whether transaction is a coinbase bool fCoinBase; - // unspent transaction outputs; spent outputs are .IsNull(); spent outputs at the end of the array are dropped + //! unspent transaction outputs; spent outputs are .IsNull(); spent outputs at the end of the array are dropped std::vector vout; - // at which height this transaction was included in the active block chain + //! at which height this transaction was included in the active block chain int nHeight; - // version of the CTransaction; accesses to this value should probably check for nHeight as well, - // as new tx version will probably only be introduced at certain heights + //! version of the CTransaction; accesses to this value should probably check for nHeight as well, + //! as new tx version will probably only be introduced at certain heights int nVersion; void FromTx(const CTransaction &tx, int nHeightIn) { @@ -92,7 +93,7 @@ public: ClearUnspendable(); } - // construct a CCoins from a CTransaction, at a given height + //! construct a CCoins from a CTransaction, at a given height CCoins(const CTransaction &tx, int nHeightIn) { FromTx(tx, nHeightIn); } @@ -104,10 +105,10 @@ public: nVersion = 0; } - // empty constructor + //! empty constructor CCoins() : fCoinBase(false), vout(0), nHeight(0), nVersion(0) { } - // remove spent outputs at the end of vout + //!remove spent outputs at the end of vout void Cleanup() { while (vout.size() > 0 && vout.back().IsNull()) vout.pop_back(); @@ -130,7 +131,7 @@ public: std::swap(to.nVersion, nVersion); } - // equality test + //! equality test friend bool operator==(const CCoins &a, const CCoins &b) { // Empty CCoins objects are always equal. if (a.IsPruned() && b.IsPruned()) @@ -236,19 +237,19 @@ public: Cleanup(); } - // mark an outpoint spent, and construct undo information + //! mark an outpoint spent, and construct undo information bool Spend(const COutPoint &out, CTxInUndo &undo); - // mark a vout spent + //! mark a vout spent bool Spend(int nPos); - // check whether a particular output is still available + //! check whether a particular output is still available bool IsAvailable(unsigned int nPos) const { return (nPos < vout.size() && !vout[nPos].IsNull()); } - // check whether the entire CCoins is spent - // note that only !IsPruned() CCoins can be serialized + //! check whether the entire CCoins is spent + //! note that only !IsPruned() CCoins can be serialized bool IsPruned() const { BOOST_FOREACH(const CTxOut &out, vout) if (!out.IsNull()) @@ -264,9 +265,12 @@ private: public: CCoinsKeyHasher(); - // This *must* return size_t. With Boost 1.46 on 32-bit systems the - // unordered_map will behave unpredictably if the custom hasher returns a - // uint64_t, resulting in failures when syncing the chain (#4634). + + /** + * This *must* return size_t. With Boost 1.46 on 32-bit systems the + * unordered_map will behave unpredictably if the custom hasher returns a + * uint64_t, resulting in failures when syncing the chain (#4634). + */ size_t operator()(const uint256& key) const { return key.GetHash(salt); } @@ -305,24 +309,24 @@ struct CCoinsStats class CCoinsView { public: - // Retrieve the CCoins (unspent transaction outputs) for a given txid + //! Retrieve the CCoins (unspent transaction outputs) for a given txid virtual bool GetCoins(const uint256 &txid, CCoins &coins) const; - // Just check whether we have data for a given txid. - // This may (but cannot always) return true for fully spent transactions + //! Just check whether we have data for a given txid. + //! This may (but cannot always) return true for fully spent transactions virtual bool HaveCoins(const uint256 &txid) const; - // Retrieve the block hash whose state this CCoinsView currently represents + //! Retrieve the block hash whose state this CCoinsView currently represents virtual uint256 GetBestBlock() const; - // Do a bulk modification (multiple CCoins changes + BestBlock change). - // The passed mapCoins can be modified. + //! Do a bulk modification (multiple CCoins changes + BestBlock change). + //! The passed mapCoins can be modified. virtual bool BatchWrite(CCoinsMap &mapCoins, const uint256 &hashBlock); - // Calculate statistics about the unspent transaction output set + //! Calculate statistics about the unspent transaction output set virtual bool GetStats(CCoinsStats &stats) const; - // As we use CCoinsViews polymorphically, have a virtual destructor + //! As we use CCoinsViews polymorphically, have a virtual destructor virtual ~CCoinsView() {} }; @@ -346,9 +350,11 @@ public: class CCoinsViewCache; -/** A reference to a mutable cache entry. Encapsulating it allows us to run +/** + * A reference to a mutable cache entry. Encapsulating it allows us to run * cleanup code after the modification is finished, and keeping track of - * concurrent modifications. */ + * concurrent modifications. + */ class CCoinsModifier { private: @@ -370,8 +376,10 @@ protected: /* Whether this cache has an active modifier. */ bool hasModifier; - /* Make mutable so that we can "fill the cache" even from Get-methods - declared as "const". */ + /** + * Make mutable so that we can "fill the cache" even from Get-methods + * declared as "const". + */ mutable uint256 hashBlock; mutable CCoinsMap cacheCoins; @@ -386,37 +394,44 @@ public: void SetBestBlock(const uint256 &hashBlock); bool BatchWrite(CCoinsMap &mapCoins, const uint256 &hashBlock); - // Return a pointer to CCoins in the cache, or NULL if not found. This is - // more efficient than GetCoins. Modifications to other cache entries are - // allowed while accessing the returned pointer. + /** + * Return a pointer to CCoins in the cache, or NULL if not found. This is + * more efficient than GetCoins. Modifications to other cache entries are + * allowed while accessing the returned pointer. + */ const CCoins* AccessCoins(const uint256 &txid) const; - // Return a modifiable reference to a CCoins. If no entry with the given - // txid exists, a new one is created. Simultaneous modifications are not - // allowed. + /** + * Return a modifiable reference to a CCoins. If no entry with the given + * txid exists, a new one is created. Simultaneous modifications are not + * allowed. + */ CCoinsModifier ModifyCoins(const uint256 &txid); - // Push the modifications applied to this cache to its base. - // Failure to call this method before destruction will cause the changes to be forgotten. - // If false is returned, the state of this cache (and its backing view) will be undefined. + /** + * Push the modifications applied to this cache to its base. + * Failure to call this method before destruction will cause the changes to be forgotten. + * If false is returned, the state of this cache (and its backing view) will be undefined. + */ bool Flush(); - // Calculate the size of the cache (in number of transactions) + //! Calculate the size of the cache (in number of transactions) unsigned int GetCacheSize() const; - /** Amount of bitcoins coming in to a transaction - Note that lightweight clients may not know anything besides the hash of previous transactions, - so may not be able to calculate this. - - @param[in] tx transaction for which we are checking input total - @return Sum of value of all inputs (scriptSigs) + /** + * Amount of bitcoins coming in to a transaction + * Note that lightweight clients may not know anything besides the hash of previous transactions, + * so may not be able to calculate this. + * + * @param[in] tx transaction for which we are checking input total + * @return Sum of value of all inputs (scriptSigs) */ CAmount GetValueIn(const CTransaction& tx) const; - // Check whether all prevouts of the transaction are present in the UTXO set represented by this view + //! Check whether all prevouts of the transaction are present in the UTXO set represented by this view bool HaveInputs(const CTransaction& tx) const; - // Return priority of tx at height nHeight + //! Return priority of tx at height nHeight double GetPriority(const CTransaction &tx, int nHeight) const; const CTxOut &GetOutputFor(const CTxIn& input) const; -- cgit v1.2.3