Merge pull request #990 from sipa/doc

Begin doxygen-compatible comments
This commit is contained in:
Wladimir J. van der Laan 2012-03-26 12:27:49 -07:00
commit 57de7cd603
18 changed files with 136 additions and 134 deletions

View file

@ -15,7 +15,7 @@
#include <openssl/rand.h> #include <openssl/rand.h>
// Extended statistics about a CAddress /** Extended statistics about a CAddress */
class CAddrInfo : public CAddress class CAddrInfo : public CAddress
{ {
private: private:
@ -160,6 +160,7 @@ public:
// the maximum number of nodes to return in a getaddr call // the maximum number of nodes to return in a getaddr call
#define ADDRMAN_GETADDR_MAX 2500 #define ADDRMAN_GETADDR_MAX 2500
/** Stochastical (IP) address manager */
class CAddrMan class CAddrMan
{ {
private: private:

View file

@ -169,7 +169,7 @@ inline bool DecodeBase58Check(const std::string& str, std::vector<unsigned char>
// Base class for all base58-encoded data /** Base class for all base58-encoded data */
class CBase58Data class CBase58Data
{ {
protected: protected:
@ -252,11 +252,12 @@ public:
bool operator> (const CBase58Data& b58) const { return CompareTo(b58) > 0; } bool operator> (const CBase58Data& b58) const { return CompareTo(b58) > 0; }
}; };
// base58-encoded bitcoin addresses /** base58-encoded bitcoin addresses.
// Public-key-hash-addresses have version 0 (or 192 testnet) * Public-key-hash-addresses have version 0 (or 111 testnet).
// The data vector contains RIPEMD160(SHA256(pubkey)), where pubkey is the serialized public key * The data vector contains RIPEMD160(SHA256(pubkey)), where pubkey is the serialized public key.
// Script-hash-addresses have version 5 (or 196 testnet) * Script-hash-addresses have version 5 (or 196 testnet).
// The data vector contains RIPEMD160(SHA256(cscript)), where cscript is the serialized redemption script * The data vector contains RIPEMD160(SHA256(cscript)), where cscript is the serialized redemption script.
*/
class CBitcoinAddress : public CBase58Data class CBitcoinAddress : public CBase58Data
{ {
public: public:
@ -356,6 +357,7 @@ public:
} }
}; };
/** A base58-encoded secret key */
class CBitcoinSecret : public CBase58Data class CBitcoinSecret : public CBase58Data
{ {
public: public:

View file

@ -11,6 +11,7 @@
#include "util.h" #include "util.h"
/** Errors thrown by the bignum class */
class bignum_error : public std::runtime_error class bignum_error : public std::runtime_error
{ {
public: public:
@ -18,7 +19,7 @@ public:
}; };
/** RAII encapsulated BN_CTX (OpenSSL bignum context) */
class CAutoBN_CTX class CAutoBN_CTX
{ {
protected: protected:
@ -46,7 +47,7 @@ public:
}; };
/** C++ wrapper for BIGNUM (OpenSSl bignum) */
class CBigNum : public BIGNUM class CBigNum : public BIGNUM
{ {
public: public:

View file

@ -10,10 +10,9 @@
class uint256; class uint256;
class CBlockIndex; 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.
// They are updated every release or three. */
//
namespace Checkpoints namespace Checkpoints
{ {
// Returns true if block passes checkpoint checks // Returns true if block passes checkpoint checks

View file

@ -25,6 +25,7 @@ with the double-sha256 of the public key as the IV, and the
master key's key as the encryption key (see keystore.[ch]). master key's key as the encryption key (see keystore.[ch]).
*/ */
/** Master key for wallet encryption */
class CMasterKey class CMasterKey
{ {
public: public:
@ -58,6 +59,7 @@ public:
typedef std::vector<unsigned char, secure_allocator<unsigned char> > CKeyingMaterial; typedef std::vector<unsigned char, secure_allocator<unsigned char> > CKeyingMaterial;
/** Encryption/decryption context with key information */
class CCrypter class CCrypter
{ {
private: private:

View file

@ -34,7 +34,7 @@ void ThreadFlushWalletDB(void* parg);
bool BackupWallet(const CWallet& wallet, const std::string& strDest); bool BackupWallet(const CWallet& wallet, const std::string& strDest);
/** RAII class that provides access to a Berkeley database */
class CDB class CDB
{ {
protected: protected:
@ -266,7 +266,7 @@ public:
/** Access to the transaction database (blkindex.dat) */
class CTxDB : public CDB class CTxDB : public CDB
{ {
public: public:
@ -297,7 +297,7 @@ public:
/** Access to the (IP) address database (addr.dat) */
class CAddrDB : public CDB class CAddrDB : public CDB
{ {
public: public:
@ -315,7 +315,7 @@ public:
bool LoadAddresses(); bool LoadAddresses();
/** A key pool entry */
class CKeyPool class CKeyPool
{ {
public: public:
@ -344,7 +344,7 @@ public:
/** Error statuses for the wallet database */
enum DBErrors enum DBErrors
{ {
DB_LOAD_OK, DB_LOAD_OK,
@ -354,6 +354,7 @@ enum DBErrors
DB_NEED_REWRITE DB_NEED_REWRITE
}; };
/** Access to the wallet database (wallet.dat) */
class CWalletDB : public CDB class CWalletDB : public CDB
{ {
public: public:

View file

@ -54,6 +54,7 @@ typedef std::vector<unsigned char, secure_allocator<unsigned char> > CPrivKey;
// CSecret is a serialization of just the secret parameter (32 bytes) // CSecret is a serialization of just the secret parameter (32 bytes)
typedef std::vector<unsigned char, secure_allocator<unsigned char> > CSecret; typedef std::vector<unsigned char, secure_allocator<unsigned char> > CSecret;
/** An encapsulated OpenSSL Elliptic Curve key (public and/or private) */
class CKey class CKey
{ {
protected: protected:

View file

@ -8,7 +8,7 @@
#include "crypter.h" #include "crypter.h"
#include "script.h" #include "script.h"
// A virtual base class for key stores /** A virtual base class for key stores */
class CKeyStore class CKeyStore
{ {
protected: protected:
@ -42,7 +42,7 @@ public:
typedef std::map<CBitcoinAddress, std::pair<CSecret, bool> > KeyMap; typedef std::map<CBitcoinAddress, std::pair<CSecret, bool> > KeyMap;
typedef std::map<uint160, CScript > ScriptMap; typedef std::map<uint160, CScript > ScriptMap;
// Basic key store, that keeps keys in an address->secret map /** Basic key store, that keeps keys in an address->secret map */
class CBasicKeyStore : public CKeyStore class CBasicKeyStore : public CKeyStore
{ {
protected: protected:
@ -92,8 +92,9 @@ public:
typedef std::map<CBitcoinAddress, std::pair<std::vector<unsigned char>, std::vector<unsigned char> > > CryptedKeyMap; typedef std::map<CBitcoinAddress, std::pair<std::vector<unsigned char>, std::vector<unsigned char> > > CryptedKeyMap;
// Keystore which keeps the private keys encrypted /** Keystore which keeps the private keys encrypted.
// It derives from the basic key store, which is used if no encryption is active. * It derives from the basic key store, which is used if no encryption is active.
*/
class CCryptoKeyStore : public CBasicKeyStore class CCryptoKeyStore : public CBasicKeyStore
{ {
private: private:

View file

@ -122,7 +122,7 @@ std::string GetWarnings(std::string strFor);
bool GetWalletFile(CWallet* pwallet, std::string &strWalletFileOut); bool GetWalletFile(CWallet* pwallet, std::string &strWalletFileOut);
/** Position on disk for a particular transaction. */
class CDiskTxPos class CDiskTxPos
{ {
public: public:
@ -174,7 +174,7 @@ public:
/** An inpoint - a combination of a transaction and an index n into its vin */
class CInPoint class CInPoint
{ {
public: public:
@ -189,7 +189,7 @@ public:
/** An outpoint - a combination of a transaction hash and an index n into its vout */
class COutPoint class COutPoint
{ {
public: public:
@ -231,11 +231,10 @@ public:
// /** An input of a transaction. It contains the location of the previous
// An input of a transaction. It contains the location of the previous * transaction's output that it claims and a signature that matches the
// transaction's output that it claims and a signature that matches the * output's public key.
// output's public key. */
//
class CTxIn class CTxIn
{ {
public: public:
@ -310,10 +309,9 @@ public:
// /** An output of a transaction. It contains the public key that the next input
// An output of a transaction. It contains the public key that the next input * must be able to sign with to claim it.
// must be able to sign with to claim it. */
//
class CTxOut class CTxOut
{ {
public: public:
@ -389,10 +387,9 @@ enum GetMinFee_mode
typedef std::map<uint256, std::pair<CTxIndex, CTransaction> > MapPrevTx; typedef std::map<uint256, std::pair<CTxIndex, CTransaction> > MapPrevTx;
// /** The basic transaction that is broadcasted on the network and contained in
// The basic transaction that is broadcasted on the network and contained in * blocks. A transaction can contain multiple inputs and outputs.
// blocks. A transaction can contain multiple inputs and outputs. */
//
class CTransaction class CTransaction
{ {
public: public:
@ -699,9 +696,7 @@ public:
// /** A transaction with a merkle branch linking it to the block chain. */
// A transaction with a merkle branch linking it to the block chain
//
class CMerkleTx : public CTransaction class CMerkleTx : public CTransaction
{ {
public: public:
@ -753,11 +748,10 @@ public:
// /** A txdb record that contains the disk location of a transaction and the
// A txdb record that contains the disk location of a transaction and the * locations of transactions that spend its outputs. vSpent is really only
// locations of transactions that spend its outputs. vSpent is really only * used as a flag, but having the location is very helpful for debugging.
// used as a flag, but having the location is very helpful for debugging. */
//
class CTxIndex class CTxIndex
{ {
public: public:
@ -812,17 +806,16 @@ public:
// /** Nodes collect new transactions into a block, hash them into a hash tree,
// Nodes collect new transactions into a block, hash them into a hash tree, * and scan through nonce values to make the block's hash satisfy proof-of-work
// and scan through nonce values to make the block's hash satisfy proof-of-work * requirements. When they solve the proof-of-work, they broadcast the block
// requirements. When they solve the proof-of-work, they broadcast the block * to everyone and the block is added to the block chain. The first transaction
// to everyone and the block is added to the block chain. The first transaction * in the block is a special one that creates a new coin owned by the creator
// in the block is a special one that creates a new coin owned by the creator * of the block.
// of the block. *
// * Blocks are appended to blk0001.dat files on disk. Their location on disk
// Blocks are appended to blk0001.dat files on disk. Their location on disk * is indexed by CBlockIndex objects in memory.
// is indexed by CBlockIndex objects in memory. */
//
class CBlock class CBlock
{ {
public: public:
@ -1040,14 +1033,13 @@ private:
// /** The block chain is a tree shaped structure starting with the
// The block chain is a tree shaped structure starting with the * genesis block at the root, with each block potentially having multiple
// genesis block at the root, with each block potentially having multiple * candidates to be the next block. pprev and pnext link a path through the
// candidates to be the next block. pprev and pnext link a path through the * main/longest chain. A blockindex may have multiple pprev pointing back
// main/longest chain. A blockindex may have multiple pprev pointing back * to it, but pnext will only point forward to the longest branch, or will
// to it, but pnext will only point forward to the longest branch, or will * be null if the block is not part of the longest chain.
// be null if the block is not part of the longest chain. */
//
class CBlockIndex class CBlockIndex
{ {
public: public:
@ -1204,9 +1196,7 @@ public:
// /** Used to marshal pointers into hashes for db storage. */
// Used to marshal pointers into hashes for db storage.
//
class CDiskBlockIndex : public CBlockIndex class CDiskBlockIndex : public CBlockIndex
{ {
public: public:
@ -1281,11 +1271,10 @@ public:
// /** Describes a place in the block chain to another node such that if the
// Describes a place in the block chain to another node such that if the * other node doesn't have the same branch, it can find a recent common trunk.
// other node doesn't have the same branch, it can find a recent common trunk. * The further back it is, the further before the fork it may be.
// The further back it is, the further before the fork it may be. */
//
class CBlockLocator class CBlockLocator
{ {
protected: protected:
@ -1417,13 +1406,12 @@ public:
// /** Alerts are for notifying old versions if they become too obsolete and
// Alerts are for notifying old versions if they become too obsolete and * need to upgrade. The message is displayed in the status bar.
// need to upgrade. The message is displayed in the status bar. * Alert messages are broadcast as a vector of signed data. Unserializing may
// Alert messages are broadcast as a vector of signed data. Unserializing may * not read the entire buffer if the alert is for a newer version, but older
// not read the entire buffer if the alert is for a newer version, but older * versions can still relay the original data.
// versions can still relay the original data. */
//
class CUnsignedAlert class CUnsignedAlert
{ {
public: public:
@ -1523,6 +1511,7 @@ public:
} }
}; };
/** An alert is a combination of a serialized CUnsignedAlert and a signature. */
class CAlert : public CUnsignedAlert class CAlert : public CUnsignedAlert
{ {
public: public:

View file

@ -7,6 +7,7 @@
#include <set> #include <set>
#include <deque> #include <deque>
/** STL-like set container that only keeps the most recent N elements. */
template <typename T> class mruset template <typename T> class mruset
{ {
public: public:

View file

@ -69,7 +69,7 @@ public:
}; };
/** Thread types */
enum threadId enum threadId
{ {
THREAD_SOCKETHANDLER, THREAD_SOCKETHANDLER,
@ -105,7 +105,7 @@ extern std::map<CInv, int64> mapAlreadyAskedFor;
/** Information about a peer */
class CNode class CNode
{ {
public: public:

View file

@ -30,7 +30,7 @@
extern int nConnectTimeout; extern int nConnectTimeout;
// IP address (IPv6, or IPv4 using mapped IPv6 range (::FFFF:0:0/96)) /** IP address (IPv6, or IPv4 using mapped IPv6 range (::FFFF:0:0/96)) */
class CNetAddr class CNetAddr
{ {
protected: protected:
@ -81,6 +81,7 @@ class CNetAddr
) )
}; };
/** A combnation of a network address (CNetAddr) and a (TCP) port */
class CService : public CNetAddr class CService : public CNetAddr
{ {
protected: protected:

View file

@ -22,15 +22,15 @@ static inline unsigned short GetDefaultPort(const bool testnet = fTestNet)
return testnet ? 18333 : 8333; return testnet ? 18333 : 8333;
} }
//
// Message header
// (4) message start
// (12) command
// (4) size
// (4) checksum
extern unsigned char pchMessageStart[4]; extern unsigned char pchMessageStart[4];
/** Message header.
* (4) message start.
* (12) command.
* (4) size.
* (4) checksum.
*/
class CMessageHeader class CMessageHeader
{ {
public: public:
@ -57,11 +57,13 @@ class CMessageHeader
unsigned int nChecksum; unsigned int nChecksum;
}; };
/** nServices flags */
enum enum
{ {
NODE_NETWORK = (1 << 0), NODE_NETWORK = (1 << 0),
}; };
/** A CService with information about it as peer */
class CAddress : public CService class CAddress : public CService
{ {
public: public:
@ -97,6 +99,7 @@ class CAddress : public CService
int64 nLastTry; int64 nLastTry;
}; };
/** inv message data */
class CInv class CInv
{ {
public: public:

View file

@ -15,6 +15,7 @@
class CTransaction; class CTransaction;
class CKeyStore; class CKeyStore;
/** Signature hash types/flags */
enum enum
{ {
SIGHASH_ALL = 1, SIGHASH_ALL = 1,
@ -36,6 +37,7 @@ enum txnouttype
const char* GetTxnOutputType(txnouttype t); const char* GetTxnOutputType(txnouttype t);
/** Script opcodes */
enum opcodetype enum opcodetype
{ {
// push value // push value
@ -212,7 +214,7 @@ inline std::string StackString(const std::vector<std::vector<unsigned char> >& v
/** Serialized script, used inside transaction inputs and outputs */
class CScript : public std::vector<unsigned char> class CScript : public std::vector<unsigned char>
{ {
protected: protected:

View file

@ -265,11 +265,11 @@ uint64 ReadCompactSize(Stream& is)
//
// Wrapper for serializing arrays and POD
// There's a clever template way to make arrays serialize normally, but MSVC6 doesn't support it
//
#define FLATDATA(obj) REF(CFlatData((char*)&(obj), (char*)&(obj) + sizeof(obj))) #define FLATDATA(obj) REF(CFlatData((char*)&(obj), (char*)&(obj) + sizeof(obj)))
/** Wrapper for serializing arrays and POD.
* There's a clever template way to make arrays serialize normally, but MSVC6 doesn't support it.
*/
class CFlatData class CFlatData
{ {
protected: protected:
@ -302,9 +302,7 @@ public:
// /** string stored as a fixed length field */
// string stored as a fixed length field
//
template<std::size_t LEN> template<std::size_t LEN>
class CFixedFieldString class CFixedFieldString
{ {
@ -856,11 +854,11 @@ struct zero_after_free_allocator : public std::allocator<T>
// /** Double ended buffer combining vector and stream-like interfaces.
// Double ended buffer combining vector and stream-like interfaces. *
// >> and << read and write unformatted data using the above serialization templates. * >> and << read and write unformatted data using the above serialization templates.
// Fills with data in linear time; some stringstream implementations take N^2 time. * Fills with data in linear time; some stringstream implementations take N^2 time.
// */
class CDataStream class CDataStream
{ {
protected: protected:
@ -1220,12 +1218,12 @@ int main(int argc, char *argv[])
// /** RAII wrapper for FILE*.
// Automatic closing wrapper for FILE* *
// - Will automatically close the file when it goes out of scope if not null. * Will automatically close the file when it goes out of scope if not null.
// - If you're returning the file pointer, return file.release(). * If you're returning the file pointer, return file.release().
// - If you need to close the file early, use file.fclose() instead of fclose(file). * If you need to close the file early, use file.fclose() instead of fclose(file).
// */
class CAutoFile class CAutoFile
{ {
protected: protected:

View file

@ -19,8 +19,9 @@ inline int Testuint256AdHoc(std::vector<std::string> vArg);
// We have to keep a separate base class without constructors /** Base class without constructors for uint256 and uint160.
// so the compiler will let us use it in a union * This makes the compiler let u use it in a union.
*/
template<unsigned int BITS> template<unsigned int BITS>
class base_uint class base_uint
{ {
@ -393,6 +394,7 @@ typedef base_uint<256> base_uint256;
// uint160 // uint160
// //
/** 160-bit unsigned integer */
class uint160 : public base_uint160 class uint160 : public base_uint160
{ {
public: public:
@ -507,6 +509,7 @@ inline const uint160 operator-(const uint160& a, const uint160& b) { return
// uint256 // uint256
// //
/** 256-bit unsigned integer */
class uint256 : public base_uint256 class uint256 : public base_uint256
{ {
public: public:

View file

@ -179,7 +179,7 @@ void AddTimeData(const CNetAddr& ip, int64 nTime);
// Wrapper to automatically initialize mutex /** Wrapper to automatically initialize mutex. */
class CCriticalSection class CCriticalSection
{ {
protected: protected:
@ -192,7 +192,7 @@ public:
bool TryEnter(const char* pszName, const char* pszFile, int nLine); bool TryEnter(const char* pszName, const char* pszFile, int nLine);
}; };
// Automatically leave critical section when leaving block, needed for exception safety /** RAII object that acquires mutex. Needed for exception safety. */
class CCriticalBlock class CCriticalBlock
{ {
protected: protected:
@ -225,6 +225,7 @@ public:
#define LEAVE_CRITICAL_SECTION(cs) \ #define LEAVE_CRITICAL_SECTION(cs) \
(cs).Leave() (cs).Leave()
/** RAII object that tries to acquire mutex. Needed for exception safety. */
class CTryCriticalBlock class CTryCriticalBlock
{ {
protected: protected:
@ -523,8 +524,9 @@ inline uint160 Hash160(const std::vector<unsigned char>& vch)
} }
// Median filter over a stream of values /** Median filter over a stream of values.
// Returns the median of the last N numbers * Returns the median of the last N numbers
*/
template <typename T> class CMedianFilter template <typename T> class CMedianFilter
{ {
private: private:

View file

@ -14,6 +14,7 @@ class CWalletTx;
class CReserveKey; class CReserveKey;
class CWalletDB; class CWalletDB;
/** (client) version numbers for particular wallet features */
enum WalletFeature enum WalletFeature
{ {
FEATURE_BASE = 10500, // the earliest version new wallets supports (only useful for getinfo's clientversion output) FEATURE_BASE = 10500, // the earliest version new wallets supports (only useful for getinfo's clientversion output)
@ -24,9 +25,9 @@ enum WalletFeature
FEATURE_LATEST = 60000 FEATURE_LATEST = 60000
}; };
// A CWallet is an extension of a keystore, which also maintains a set of /** A CWallet is an extension of a keystore, which also maintains a set of transactions and balances,
// transactions and balances, and provides the ability to create new * and provides the ability to create new transactions.
// transactions */
class CWallet : public CCryptoKeyStore class CWallet : public CCryptoKeyStore
{ {
private: private:
@ -245,7 +246,7 @@ public:
int GetVersion() { return nWalletVersion; } int GetVersion() { return nWalletVersion; }
}; };
/** A key allocated from the key pool. */
class CReserveKey class CReserveKey
{ {
protected: protected:
@ -271,11 +272,9 @@ public:
}; };
// /** 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 * It includes any unrecorded transactions needed to link it back to the block chain.
// about. It includes any unrecorded transactions needed to link it back */
// to the block chain.
//
class CWalletTx : public CMerkleTx class CWalletTx : public CMerkleTx
{ {
private: private:
@ -580,9 +579,7 @@ public:
}; };
// /** Private key that includes an expiration date in case it never gets used. */
// Private key that includes an expiration date in case it never gets used.
//
class CWalletKey class CWalletKey
{ {
public: public:
@ -615,10 +612,9 @@ public:
// /** Account information.
// Account information. * Stored in wallet with key "acc"+string account name.
// Stored in wallet with key "acc"+string account name */
//
class CAccount class CAccount
{ {
public: public:
@ -644,10 +640,9 @@ public:
// /** Internal transfers.
// Internal transfers. * Database key is acentry<account><counter>.
// Database key is acentry<account><counter> */
//
class CAccountingEntry class CAccountingEntry
{ {
public: public: