Skip to content

Commit

Permalink
Convert remaining comments in /src to doxygen format
Browse files Browse the repository at this point in the history 
- 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
  • Loading branch information
@fanquake @laanwj
fanquake authored and laanwj committed Nov 21, 2014
1 parent f2ada13 commit fa94b9d
Show file tree
Hide file tree
Showing 19 changed files with 269 additions and 225 deletions.
4 changes: 2 additions & 2 deletions src/base58.cpp
View file
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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)
Expand Down
24 changes: 12 additions & 12 deletions src/base58.h
View file
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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;

Expand Down
20 changes: 12 additions & 8 deletions src/bloom.cpp
View file
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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)),
Expand Down
36 changes: 20 additions & 16 deletions src/bloom.h
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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,
Expand Down Expand Up @@ -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) {}

Expand All @@ -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();
};

Expand Down
16 changes: 9 additions & 7 deletions src/checkpoints.cpp
View file
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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;
Expand All @@ -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;
Expand Down
13 changes: 7 additions & 6 deletions src/checkpoints.h
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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);
Expand Down
50 changes: 27 additions & 23 deletions src/checkqueue.h
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
*
Expand All @@ -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;
Expand Down Expand Up @@ -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);
Expand All @@ -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
Expand Down
14 changes: 8 additions & 6 deletions src/coins.cpp
View file
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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++) {
Expand Down Expand Up @@ -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());
Expand Down
Loading

0 comments on commit fa94b9d

Please sign in to comment.