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

Author: fanquake

src/base58.cpp

@@ -1,5 +1,5 @@
 // Copyright (c) 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 "base58.h"
@@ -15,7 +15,7 @@
 #include <boost/variant/apply_visitor.hpp>
 #include <boost/variant/static_visitor.hpp>
 
-/* All alphanumeric characters except for "0", "I", "O", and "l" */
+/** All alphanumeric characters except for "0", "I", "O", and "l" */
 static const char* pszBase58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 
 bool DecodeBase58(const char* psz, std::vector<unsigned char>& vch)

src/base58.h

@@ -1,16 +1,16 @@
 // 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.
 
-//
-// Why base-58 instead of standard base-64 encoding?
-// - Don't want 0OIl characters that look the same in some fonts and
-//      could be used to create visually identical looking account numbers.
-// - A string with non-alphanumeric characters is not as easily accepted as an account number.
-// - E-mail usually won't line-break if there's no punctuation to break at.
-// - Double-clicking selects the whole number as one word if it's all alphanumeric.
-//
+/**
+ * Why base-58 instead of standard base-64 encoding?
+ * - Don't want 0OIl characters that look the same in some fonts and
+ *      could be used to create visually identical looking account numbers.
+ * - A string with non-alphanumeric characters is not as easily accepted as an account number.
+ * - E-mail usually won't line-break if there's no punctuation to break at.
+ * - Double-clicking selects the whole number as one word if it's all alphanumeric.
+ */
 #ifndef BITCOIN_BASE58_H
 #define BITCOIN_BASE58_H
 
@@ -70,10 +70,10 @@ inline bool DecodeBase58Check(const std::string& str, std::vector<unsigned char>
 class CBase58Data
 {
 protected:
-    // the version byte(s)
+    //! the version byte(s)
     std::vector<unsigned char> vchVersion;
 
-    // the actually encoded data
+    //! the actually encoded data
     typedef std::vector<unsigned char, zero_after_free_allocator<unsigned char> > vector_uchar;
     vector_uchar vchData;
 

src/bloom.cpp

@@ -1,5 +1,5 @@
-// Copyright (c) 2012 The Bitcoin developers
-// Distributed under the MIT/X11 software license, see the accompanying
+// Copyright (c) 2012-2014 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
 #include "bloom.h"
@@ -21,13 +21,17 @@
 using namespace std;
 
 CBloomFilter::CBloomFilter(unsigned int nElements, double nFPRate, unsigned int nTweakIn, unsigned char nFlagsIn) :
-// The ideal size for a bloom filter with a given number of elements and false positive rate is:
-// - nElements * log(fp rate) / ln(2)^2
-// We ignore filter parameters which will create a bloom filter larger than the protocol limits
+/**
+ * The ideal size for a bloom filter with a given number of elements and false positive rate is:
+ * - nElements * log(fp rate) / ln(2)^2
+ * We ignore filter parameters which will create a bloom filter larger than the protocol limits
+ */
 vData(min((unsigned int)(-1  / LN2SQUARED * nElements * log(nFPRate)), MAX_BLOOM_FILTER_SIZE * 8) / 8),
-// The ideal number of hash functions is filter size * ln(2) / number of elements
-// Again, we ignore filter parameters which will create a bloom filter with more hash functions than the protocol limits
-// See http://en.wikipedia.org/wiki/Bloom_filter for an explanation of these formulas
+/**
+ * The ideal number of hash functions is filter size * ln(2) / number of elements
+ * Again, we ignore filter parameters which will create a bloom filter with more hash functions than the protocol limits
+ * See https://en.wikipedia.org/wiki/Bloom_filter for an explanation of these formulas
+ */
 isFull(false),
 isEmpty(false),
 nHashFuncs(min((unsigned int)(vData.size() * 8 / nElements * LN2), MAX_HASH_FUNCS)),

src/bloom.h

@@ -1,5 +1,5 @@
-// Copyright (c) 2012 The Bitcoin developers
-// Distributed under the MIT/X11 software license, see the accompanying
+// Copyright (c) 2012-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_BLOOM_H
@@ -13,12 +13,14 @@ class COutPoint;
 class CTransaction;
 class uint256;
 
-// 20,000 items with fp rate < 0.1% or 10,000 items and <0.0001%
+//! 20,000 items with fp rate < 0.1% or 10,000 items and <0.0001%
 static const unsigned int MAX_BLOOM_FILTER_SIZE = 36000; // bytes
 static const unsigned int MAX_HASH_FUNCS = 50;
 
-// First two bits of nFlags control how much IsRelevantAndUpdate actually updates
-// The remaining bits are reserved
+/**
+ * First two bits of nFlags control how much IsRelevantAndUpdate actually updates
+ * The remaining bits are reserved
+ */
 enum bloomflags
 {
     BLOOM_UPDATE_NONE = 0,
@@ -52,13 +54,15 @@ class CBloomFilter
     unsigned int Hash(unsigned int nHashNum, const std::vector<unsigned char>& vDataToHash) const;
 
 public:
-    // Creates a new bloom filter which will provide the given fp rate when filled with the given number of elements
-    // Note that if the given parameters will result in a filter outside the bounds of the protocol limits,
-    // the filter created will be as close to the given parameters as possible within the protocol limits.
-    // This will apply if nFPRate is very low or nElements is unreasonably high.
-    // nTweak is a constant which is added to the seed value passed to the hash function
-    // It should generally always be a random value (and is largely only exposed for unit testing)
-    // nFlags should be one of the BLOOM_UPDATE_* enums (not _MASK)
+    /**
+     * Creates a new bloom filter which will provide the given fp rate when filled with the given number of elements
+     * Note that if the given parameters will result in a filter outside the bounds of the protocol limits,
+     * the filter created will be as close to the given parameters as possible within the protocol limits.
+     * This will apply if nFPRate is very low or nElements is unreasonably high.
+     * nTweak is a constant which is added to the seed value passed to the hash function
+     * It should generally always be a random value (and is largely only exposed for unit testing)
+     * nFlags should be one of the BLOOM_UPDATE_* enums (not _MASK)
+     */
     CBloomFilter(unsigned int nElements, double nFPRate, unsigned int nTweak, unsigned char nFlagsIn);
     CBloomFilter() : isFull(true), isEmpty(false), nHashFuncs(0), nTweak(0), nFlags(0) {}
 
@@ -82,14 +86,14 @@ class CBloomFilter
 
     void clear();
 
-    // True if the size is <= MAX_BLOOM_FILTER_SIZE and the number of hash functions is <= MAX_HASH_FUNCS
-    // (catch a filter which was just deserialized which was too big)
+    //! True if the size is <= MAX_BLOOM_FILTER_SIZE and the number of hash functions is <= MAX_HASH_FUNCS
+    //! (catch a filter which was just deserialized which was too big)
     bool IsWithinSizeConstraints() const;
 
-    // Also adds any outputs which match the filter to the filter (to match their spending txes)
+    //! Also adds any outputs which match the filter to the filter (to match their spending txes)
     bool IsRelevantAndUpdate(const CTransaction& tx);
 
-    // Checks for empty and full filters to avoid wasting cpu
+    //! Checks for empty and full filters to avoid wasting cpu
     void UpdateEmptyFull();
 };
 

src/checkpoints.cpp

@@ -1,5 +1,5 @@
 // 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 "checkpoints.h"
@@ -14,11 +14,13 @@
 
 namespace Checkpoints {
 
-    // How many times we expect transactions after the last checkpoint to
-    // be slower. This number is a compromise, as it can't be accurate for
-    // every system. When reindexing from a fast disk with a slow CPU, it
-    // can be up to 20, while when downloading from a slow network with a
-    // fast multicore CPU, it won't be much higher than 1.
+    /**
+     * How many times we expect transactions after the last checkpoint to
+     * be slower. This number is a compromise, as it can't be accurate for
+     * every system. When reindexing from a fast disk with a slow CPU, it
+     * can be up to 20, while when downloading from a slow network with a
+     * fast multicore CPU, it won't be much higher than 1.
+     */
     static const double SIGCHECK_VERIFICATION_FACTOR = 5.0;
 
     bool fEnabled = true;
@@ -35,7 +37,7 @@ namespace Checkpoints {
         return hash == i->second;
     }
 
-    // Guess how far we are in the verification process at the given block index
+    //! Guess how far we are in the verification process at the given block index
     double GuessVerificationProgress(CBlockIndex *pindex, bool fSigchecks) {
         if (pindex==NULL)
             return 0.0;

src/checkpoints.h

@@ -1,5 +1,5 @@
-// 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_CHECKPOINTS_H
@@ -11,7 +11,8 @@
 
 class CBlockIndex;
 
-/** Block-chain checkpoints are compiled-in sanity checks.
+/** 
+ * Block-chain checkpoints are compiled-in sanity checks.
  * They are updated every release or three.
  */
 namespace Checkpoints
@@ -25,13 +26,13 @@ struct CCheckpointData {
     double fTransactionsPerDay;
 };
 
-// Returns true if block passes checkpoint checks
+//! Returns true if block passes checkpoint checks
 bool CheckBlock(int nHeight, const uint256& hash);
 
-// Return conservative estimate of total number of blocks, 0 if unknown
+//! Return conservative estimate of total number of blocks, 0 if unknown
 int GetTotalBlocksEstimate();
 
-// Returns last CBlockIndex* in mapBlockIndex that is a checkpoint
+//! Returns last CBlockIndex* in mapBlockIndex that is a checkpoint
 CBlockIndex* GetLastCheckpoint();
 
 double GuessVerificationProgress(CBlockIndex* pindex, bool fSigchecks = true);

src/checkqueue.h

@@ -1,5 +1,5 @@
-// Copyright (c) 2012 The Bitcoin developers
-// Distributed under the MIT/X11 software license, see the accompanying
+// Copyright (c) 2012-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_CHECKQUEUE_H
@@ -16,7 +16,8 @@
 template <typename T>
 class CCheckQueueControl;
 
-/** Queue for verifications that have to be performed.
+/** 
+ * Queue for verifications that have to be performed.
   * The verifications are represented by a type T, which must provide an
   * operator(), returning a bool.
   *
@@ -29,40 +30,42 @@ template <typename T>
 class CCheckQueue
 {
 private:
-    // Mutex to protect the inner state
+    //! Mutex to protect the inner state
     boost::mutex mutex;
 
-    // Worker threads block on this when out of work
+    //! Worker threads block on this when out of work
     boost::condition_variable condWorker;
 
-    // Master thread blocks on this when out of work
+    //! Master thread blocks on this when out of work
     boost::condition_variable condMaster;
 
-    // The queue of elements to be processed.
-    // As the order of booleans doesn't matter, it is used as a LIFO (stack)
+    //! The queue of elements to be processed.
+    //! As the order of booleans doesn't matter, it is used as a LIFO (stack)
     std::vector<T> queue;
 
-    // The number of workers (including the master) that are idle.
+    //! The number of workers (including the master) that are idle.
     int nIdle;
 
-    // The total number of workers (including the master).
+    //! The total number of workers (including the master).
     int nTotal;
 
-    // The temporary evaluation result.
+    //! The temporary evaluation result.
     bool fAllOk;
 
-    // Number of verifications that haven't completed yet.
-    // This includes elements that are not anymore in queue, but still in
-    // worker's own batches.
+    /**
+     * Number of verifications that haven't completed yet.
+     * This includes elements that are not anymore in queue, but still in
+     * worker's own batches.
+     */
     unsigned int nTodo;
 
-    // Whether we're shutting down.
+    //! Whether we're shutting down.
     bool fQuit;
 
-    // The maximum number of elements to be processed in one batch
+    //! The maximum number of elements to be processed in one batch
     unsigned int nBatchSize;
 
-    // Internal function that does bulk of the verification work.
+    /** Internal function that does bulk of the verification work. */
     bool Loop(bool fMaster = false)
     {
         boost::condition_variable& cond = fMaster ? condMaster : condWorker;
@@ -124,22 +127,22 @@ class CCheckQueue
     }
 
 public:
-    // Create a new check queue
+    //! Create a new check queue
     CCheckQueue(unsigned int nBatchSizeIn) : nIdle(0), nTotal(0), fAllOk(true), nTodo(0), fQuit(false), nBatchSize(nBatchSizeIn) {}
 
-    // Worker thread
+    //! Worker thread
     void Thread()
     {
         Loop();
     }
 
-    // Wait until execution finishes, and return whether all evaluations where succesful.
+    //! Wait until execution finishes, and return whether all evaluations where successful.
     bool Wait()
     {
         return Loop(true);
     }
 
-    // Add a batch of checks to the queue
+    //! Add a batch of checks to the queue
     void Add(std::vector<T>& vChecks)
     {
         boost::unique_lock<boost::mutex> lock(mutex);
@@ -161,8 +164,9 @@ class CCheckQueue
     friend class CCheckQueueControl<T>;
 };
 
-/** RAII-style controller object for a CCheckQueue that guarantees the passed
- *  queue is finished before continuing.
+/** 
+ * RAII-style controller object for a CCheckQueue that guarantees the passed
+ * queue is finished before continuing.
  */
 template <typename T>
 class CCheckQueueControl

src/coins.cpp

@@ -1,5 +1,5 @@
-// Copyright (c) 2012-2013 The Bitcoin developers
-// Distributed under the MIT/X11 software license, see the accompanying
+// Copyright (c) 2012-2014 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
 #include "coins.h"
@@ -8,9 +8,11 @@
 
 #include <assert.h>
 
-// calculate number of bytes for the bitmask, and its number of non-zero bytes
-// each bit in the bitmask represents the availability of one output, but the
-// availabilities of the first two outputs are encoded separately
+/**
+ * calculate number of bytes for the bitmask, and its number of non-zero bytes
+ * each bit in the bitmask represents the availability of one output, but the
+ * availabilities of the first two outputs are encoded separately
+ */
 void CCoins::CalcMaskSize(unsigned int &nBytes, unsigned int &nNonzeroBytes) const {
     unsigned int nLastUsedByte = 0;
     for (unsigned int b = 0; 2+b*8 < vout.size(); b++) {
@@ -133,7 +135,7 @@ const CCoins* CCoinsViewCache::AccessCoins(const uint256 &txid) const {
 bool CCoinsViewCache::HaveCoins(const uint256 &txid) const {
     CCoinsMap::const_iterator it = FetchCoins(txid);
     // We're using vtx.empty() instead of IsPruned here for performance reasons,
-    // as we only care about the case where an transaction was replaced entirely
+    // as we only care about the case where a transaction was replaced entirely
     // in a reorganization (which wipes vout entirely, as opposed to spending
     // which just cleans individual outputs).
     return (it != cacheCoins.end() && !it->second.coins.vout.empty());