From 6b8de05d0a6696dff4b7dccec5b74889f3cdc486 Mon Sep 17 00:00:00 2001 From: Pieter Wuille Date: Mon, 26 Mar 2012 16:48:23 +0200 Subject: [PATCH] Begin doxygen-compatible comments --- src/addrman.h | 3 +- src/base58.h | 14 ++++--- src/bignum.h | 5 ++- src/checkpoints.h | 7 ++-- src/crypter.h | 2 + src/db.h | 11 ++--- src/key.h | 1 + src/keystore.h | 9 ++-- src/main.h | 105 +++++++++++++++++++++------------------------- src/mruset.h | 1 + src/net.h | 4 +- src/netbase.h | 3 +- src/protocol.h | 15 ++++--- src/script.h | 4 +- src/serialize.h | 34 +++++++-------- src/uint256.h | 7 +++- src/util.h | 10 +++-- src/wallet.h | 35 +++++++--------- 18 files changed, 136 insertions(+), 134 deletions(-) diff --git a/src/addrman.h b/src/addrman.h index 350ecb27..91e1f87f 100644 --- a/src/addrman.h +++ b/src/addrman.h @@ -15,7 +15,7 @@ #include -// Extended statistics about a CAddress +/** Extended statistics about a CAddress */ class CAddrInfo : public CAddress { private: @@ -160,6 +160,7 @@ public: // the maximum number of nodes to return in a getaddr call #define ADDRMAN_GETADDR_MAX 2500 +/** Stochastical (IP) address manager */ class CAddrMan { private: diff --git a/src/base58.h b/src/base58.h index 71168cfa..755e34c4 100644 --- a/src/base58.h +++ b/src/base58.h @@ -169,7 +169,7 @@ inline bool DecodeBase58Check(const std::string& str, std::vector -// Base class for all base58-encoded data +/** Base class for all base58-encoded data */ class CBase58Data { protected: @@ -252,11 +252,12 @@ public: bool operator> (const CBase58Data& b58) const { return CompareTo(b58) > 0; } }; -// base58-encoded bitcoin addresses -// Public-key-hash-addresses have version 0 (or 192 testnet) -// The data vector contains RIPEMD160(SHA256(pubkey)), where pubkey is the serialized public key -// Script-hash-addresses have version 5 (or 196 testnet) -// The data vector contains RIPEMD160(SHA256(cscript)), where cscript is the serialized redemption script +/** base58-encoded bitcoin addresses. + * Public-key-hash-addresses have version 0 (or 111 testnet). + * The data vector contains RIPEMD160(SHA256(pubkey)), where pubkey is the serialized public key. + * Script-hash-addresses have version 5 (or 196 testnet). + * The data vector contains RIPEMD160(SHA256(cscript)), where cscript is the serialized redemption script. + */ class CBitcoinAddress : public CBase58Data { public: @@ -356,6 +357,7 @@ public: } }; +/** A base58-encoded secret key */ class CBitcoinSecret : public CBase58Data { public: diff --git a/src/bignum.h b/src/bignum.h index a750025f..c7c2ff17 100644 --- a/src/bignum.h +++ b/src/bignum.h @@ -11,6 +11,7 @@ #include "util.h" +/** Errors thrown by the bignum class */ class bignum_error : public std::runtime_error { public: @@ -18,7 +19,7 @@ public: }; - +/** RAII encapsulated BN_CTX (OpenSSL bignum context) */ class CAutoBN_CTX { protected: @@ -46,7 +47,7 @@ public: }; - +/** C++ wrapper for BIGNUM (OpenSSl bignum) */ class CBigNum : public BIGNUM { public: diff --git a/src/checkpoints.h b/src/checkpoints.h index ac2076c8..38902ac0 100644 --- a/src/checkpoints.h +++ b/src/checkpoints.h @@ -10,10 +10,9 @@ class uint256; class CBlockIndex; -// -// Block-chain checkpoints are compiled-in sanity checks. -// They are updated every release or three. -// +/** Block-chain checkpoints are compiled-in sanity checks. + * They are updated every release or three. + */ namespace Checkpoints { // Returns true if block passes checkpoint checks diff --git a/src/crypter.h b/src/crypter.h index b7fc7888..0f9ea021 100644 --- a/src/crypter.h +++ b/src/crypter.h @@ -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 for wallet encryption */ class CMasterKey { public: @@ -58,6 +59,7 @@ public: typedef std::vector > CKeyingMaterial; +/** Encryption/decryption context with key information */ class CCrypter { private: diff --git a/src/db.h b/src/db.h index 2a869d51..430880e9 100644 --- a/src/db.h +++ b/src/db.h @@ -34,7 +34,7 @@ void ThreadFlushWalletDB(void* parg); bool BackupWallet(const CWallet& wallet, const std::string& strDest); - +/** RAII class that provides access to a Berkeley database */ class CDB { protected: @@ -266,7 +266,7 @@ public: - +/** Access to the transaction database (blkindex.dat) */ class CTxDB : public CDB { public: @@ -297,7 +297,7 @@ public: - +/** Access to the (IP) address database (addr.dat) */ class CAddrDB : public CDB { public: @@ -315,7 +315,7 @@ public: bool LoadAddresses(); - +/** A key pool entry */ class CKeyPool { public: @@ -344,7 +344,7 @@ public: - +/** Error statuses for the wallet database */ enum DBErrors { DB_LOAD_OK, @@ -354,6 +354,7 @@ enum DBErrors DB_NEED_REWRITE }; +/** Access to the wallet database (wallet.dat) */ class CWalletDB : public CDB { public: diff --git a/src/key.h b/src/key.h index 4058f115..b8fc0cd7 100644 --- a/src/key.h +++ b/src/key.h @@ -54,6 +54,7 @@ typedef std::vector > CPrivKey; // CSecret is a serialization of just the secret parameter (32 bytes) typedef std::vector > CSecret; +/** An encapsulated OpenSSL Elliptic Curve key (public and/or private) */ class CKey { protected: diff --git a/src/keystore.h b/src/keystore.h index 6757834b..c32db262 100644 --- a/src/keystore.h +++ b/src/keystore.h @@ -8,7 +8,7 @@ #include "crypter.h" #include "script.h" -// A virtual base class for key stores +/** A virtual base class for key stores */ class CKeyStore { protected: @@ -42,7 +42,7 @@ public: typedef std::map > KeyMap; typedef std::map 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 { protected: @@ -92,8 +92,9 @@ public: typedef std::map, std::vector > > CryptedKeyMap; -// Keystore which keeps the private keys encrypted -// It derives from the basic key store, which is used if no encryption is active. +/** Keystore which keeps the private keys encrypted. + * It derives from the basic key store, which is used if no encryption is active. + */ class CCryptoKeyStore : public CBasicKeyStore { private: diff --git a/src/main.h b/src/main.h index 560bff0c..10bc29fc 100644 --- a/src/main.h +++ b/src/main.h @@ -122,7 +122,7 @@ std::string GetWarnings(std::string strFor); bool GetWalletFile(CWallet* pwallet, std::string &strWalletFileOut); - +/** Position on disk for a particular transaction. */ class CDiskTxPos { public: @@ -174,7 +174,7 @@ public: - +/** An inpoint - a combination of a transaction and an index n into its vin */ class CInPoint { public: @@ -189,7 +189,7 @@ public: - +/** An outpoint - a combination of a transaction hash and an index n into its vout */ class COutPoint { public: @@ -231,11 +231,10 @@ public: -// -// An input of a transaction. It contains the location of the previous -// transaction's output that it claims and a signature that matches the -// output's public key. -// +/** An input of a transaction. It contains the location of the previous + * transaction's output that it claims and a signature that matches the + * output's public key. + */ class CTxIn { public: @@ -310,10 +309,9 @@ public: -// -// An output of a transaction. It contains the public key that the next input -// must be able to sign with to claim it. -// +/** An output of a transaction. It contains the public key that the next input + * must be able to sign with to claim it. + */ class CTxOut { public: @@ -389,10 +387,9 @@ enum GetMinFee_mode typedef std::map > MapPrevTx; -// -// The basic transaction that is broadcasted on the network and contained in -// blocks. A transaction can contain multiple inputs and outputs. -// +/** The basic transaction that is broadcasted on the network and contained in + * blocks. A transaction can contain multiple inputs and outputs. + */ class CTransaction { 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 { public: @@ -753,11 +748,10 @@ public: -// -// A txdb record that contains the disk location of a transaction and the -// locations of transactions that spend its outputs. vSpent is really only -// used as a flag, but having the location is very helpful for debugging. -// +/** A txdb record that contains the disk location of a transaction and the + * locations of transactions that spend its outputs. vSpent is really only + * used as a flag, but having the location is very helpful for debugging. + */ class CTxIndex { public: @@ -812,17 +806,16 @@ public: -// -// 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 -// 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 -// in the block is a special one that creates a new coin owned by the creator -// of the block. -// -// Blocks are appended to blk0001.dat files on disk. Their location on disk -// is indexed by CBlockIndex objects in memory. -// +/** 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 + * 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 + * in the block is a special one that creates a new coin owned by the creator + * of the block. + * + * Blocks are appended to blk0001.dat files on disk. Their location on disk + * is indexed by CBlockIndex objects in memory. + */ class CBlock { public: @@ -1040,14 +1033,13 @@ private: -// -// The block chain is a tree shaped structure starting with the -// 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 -// 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 -// be null if the block is not part of the longest chain. -// +/** The block chain is a tree shaped structure starting with the + * 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 + * 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 + * be null if the block is not part of the longest chain. + */ class CBlockIndex { 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 { public: @@ -1281,11 +1271,10 @@ public: -// -// 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. -// The further back it is, the further before the fork it may be. -// +/** 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. + * The further back it is, the further before the fork it may be. + */ class CBlockLocator { protected: @@ -1417,13 +1406,12 @@ public: -// -// Alerts are for notifying old versions if they become too obsolete and -// need to upgrade. The message is displayed in the status bar. -// 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 -// versions can still relay the original data. -// +/** Alerts are for notifying old versions if they become too obsolete and + * need to upgrade. The message is displayed in the status bar. + * 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 + * versions can still relay the original data. + */ class CUnsignedAlert { public: @@ -1523,6 +1511,7 @@ public: } }; +/** An alert is a combination of a serialized CUnsignedAlert and a signature. */ class CAlert : public CUnsignedAlert { public: diff --git a/src/mruset.h b/src/mruset.h index 0cf65853..b21f1856 100644 --- a/src/mruset.h +++ b/src/mruset.h @@ -7,6 +7,7 @@ #include #include +/** STL-like set container that only keeps the most recent N elements. */ template class mruset { public: diff --git a/src/net.h b/src/net.h index b44cc5d9..ed9954bd 100644 --- a/src/net.h +++ b/src/net.h @@ -69,7 +69,7 @@ public: }; - +/** Thread types */ enum threadId { THREAD_SOCKETHANDLER, @@ -105,7 +105,7 @@ extern std::map mapAlreadyAskedFor; - +/** Information about a peer */ class CNode { public: diff --git a/src/netbase.h b/src/netbase.h index e65e138e..b5f9d5fa 100644 --- a/src/netbase.h +++ b/src/netbase.h @@ -30,7 +30,7 @@ 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 { protected: @@ -81,6 +81,7 @@ class CNetAddr ) }; +/** A combnation of a network address (CNetAddr) and a (TCP) port */ class CService : public CNetAddr { protected: diff --git a/src/protocol.h b/src/protocol.h index 613c47f0..e6391273 100644 --- a/src/protocol.h +++ b/src/protocol.h @@ -22,15 +22,15 @@ static inline unsigned short GetDefaultPort(const bool testnet = fTestNet) return testnet ? 18333 : 8333; } -// -// Message header -// (4) message start -// (12) command -// (4) size -// (4) checksum extern unsigned char pchMessageStart[4]; +/** Message header. + * (4) message start. + * (12) command. + * (4) size. + * (4) checksum. + */ class CMessageHeader { public: @@ -57,11 +57,13 @@ class CMessageHeader unsigned int nChecksum; }; +/** nServices flags */ enum { NODE_NETWORK = (1 << 0), }; +/** A CService with information about it as peer */ class CAddress : public CService { public: @@ -97,6 +99,7 @@ class CAddress : public CService int64 nLastTry; }; +/** inv message data */ class CInv { public: diff --git a/src/script.h b/src/script.h index 46f2d31b..524d08b3 100644 --- a/src/script.h +++ b/src/script.h @@ -15,6 +15,7 @@ class CTransaction; class CKeyStore; +/** Signature hash types/flags */ enum { SIGHASH_ALL = 1, @@ -36,6 +37,7 @@ enum txnouttype const char* GetTxnOutputType(txnouttype t); +/** Script opcodes */ enum opcodetype { // push value @@ -212,7 +214,7 @@ inline std::string StackString(const std::vector >& v - +/** Serialized script, used inside transaction inputs and outputs */ class CScript : public std::vector { protected: diff --git a/src/serialize.h b/src/serialize.h index c046bf37..25777fe3 100644 --- a/src/serialize.h +++ b/src/serialize.h @@ -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))) + +/** 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 { protected: @@ -302,9 +302,7 @@ public: -// -// string stored as a fixed length field -// +/** string stored as a fixed length field */ template class CFixedFieldString { @@ -856,11 +854,11 @@ struct zero_after_free_allocator : public std::allocator -// -// Double ended buffer combining vector and stream-like interfaces. -// >> and << read and write unformatted data using the above serialization templates. -// Fills with data in linear time; some stringstream implementations take N^2 time. -// +/** Double ended buffer combining vector and stream-like interfaces. + * + * >> and << read and write unformatted data using the above serialization templates. + * Fills with data in linear time; some stringstream implementations take N^2 time. + */ class CDataStream { protected: @@ -1220,12 +1218,12 @@ int main(int argc, char *argv[]) -// -// Automatic closing wrapper for FILE* -// - 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 need to close the file early, use file.fclose() instead of fclose(file). -// +/** RAII wrapper for FILE*. + * + * 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 need to close the file early, use file.fclose() instead of fclose(file). + */ class CAutoFile { protected: diff --git a/src/uint256.h b/src/uint256.h index 783e7069..cfc2eb12 100644 --- a/src/uint256.h +++ b/src/uint256.h @@ -19,8 +19,9 @@ inline int Testuint256AdHoc(std::vector vArg); -// We have to keep a separate base class without constructors -// so the compiler will let us use it in a union +/** Base class without constructors for uint256 and uint160. + * This makes the compiler let u use it in a union. + */ template class base_uint { @@ -393,6 +394,7 @@ typedef base_uint<256> base_uint256; // uint160 // +/** 160-bit unsigned integer */ class uint160 : public base_uint160 { public: @@ -507,6 +509,7 @@ inline const uint160 operator-(const uint160& a, const uint160& b) { return // uint256 // +/** 256-bit unsigned integer */ class uint256 : public base_uint256 { public: diff --git a/src/util.h b/src/util.h index a2e14198..4fa5a089 100644 --- a/src/util.h +++ b/src/util.h @@ -179,7 +179,7 @@ void AddTimeData(const CNetAddr& ip, int64 nTime); -// Wrapper to automatically initialize mutex +/** Wrapper to automatically initialize mutex. */ class CCriticalSection { protected: @@ -192,7 +192,7 @@ public: 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 { protected: @@ -225,6 +225,7 @@ public: #define LEAVE_CRITICAL_SECTION(cs) \ (cs).Leave() +/** RAII object that tries to acquire mutex. Needed for exception safety. */ class CTryCriticalBlock { protected: @@ -523,8 +524,9 @@ inline uint160 Hash160(const std::vector& vch) } -// Median filter over a stream of values -// Returns the median of the last N numbers +/** Median filter over a stream of values. + * Returns the median of the last N numbers + */ template class CMedianFilter { private: diff --git a/src/wallet.h b/src/wallet.h index 6a6ee0c4..e1065cff 100644 --- a/src/wallet.h +++ b/src/wallet.h @@ -14,6 +14,7 @@ class CWalletTx; class CReserveKey; class CWalletDB; +/** (client) version numbers for particular wallet features */ enum WalletFeature { 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 }; -// 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 +/** 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 { private: @@ -245,7 +246,7 @@ public: int GetVersion() { return nWalletVersion; } }; - +/** A key allocated from the key pool. */ class CReserveKey { protected: @@ -271,11 +272,9 @@ public: }; -// -// 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. -// +/** 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 { 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 { public: @@ -615,10 +612,9 @@ public: -// -// Account information. -// Stored in wallet with key "acc"+string account name -// +/** Account information. + * Stored in wallet with key "acc"+string account name. + */ class CAccount { public: @@ -644,10 +640,9 @@ public: -// -// Internal transfers. -// Database key is acentry -// +/** Internal transfers. + * Database key is acentry. + */ class CAccountingEntry { public: