Merge pull request #990 from sipa/doc

Begin doxygen-compatible comments

src/addrman.h

@@ -15,7 +15,7 @@
 #include <openssl/rand.h>
 
 
-// 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:

src/base58.h

@@ -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
 {
 protected:
@@ -252,11 +252,12 @@ public:
     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
 {
 public:
@@ -356,6 +357,7 @@ public:
     }
 };
 
+/** A base58-encoded secret key */
 class CBitcoinSecret : public CBase58Data
 {
 public:

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:

src/checkpoints.h

@@ -10,10 +10,9 @@
 class uint256;
 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
 {
     // Returns true if block passes checkpoint checks

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<unsigned char, secure_allocator<unsigned char> > CKeyingMaterial;
 
+/** Encryption/decryption context with key information */
 class CCrypter
 {
 private:

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:

src/key.h

@@ -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)
 typedef std::vector<unsigned char, secure_allocator<unsigned char> > CSecret;
 
+/** An encapsulated OpenSSL Elliptic Curve key (public and/or private) */
 class CKey
 {
 protected:

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<CBitcoinAddress, std::pair<CSecret, bool> > KeyMap;
 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
 {
 protected:
@@ -92,8 +92,9 @@ public:
 
 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
 {
 private:

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
-// 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
 {
 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
 {
 public:
@@ -389,10 +387,9 @@ enum GetMinFee_mode
 
 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
 {
 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
-// 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
 {
 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
 {
 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
 {
 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
-// 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
 {
 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
 {
 public:
@@ -1523,6 +1511,7 @@ public:
     }
 };
 
+/** An alert is a combination of a serialized CUnsignedAlert and a signature. */
 class CAlert : public CUnsignedAlert
 {
 public:

src/mruset.h

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

src/net.h

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

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:

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:

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<std::vector<unsigned char> >& v
 
 
 
-
+/** Serialized script, used inside transaction inputs and outputs */
 class CScript : public std::vector<unsigned char>
 {
 protected:

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<std::size_t LEN>
 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
 {
 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
 {
 protected:

src/uint256.h

@@ -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>
 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:

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<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
 {
 private:

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
+/** 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
 {
 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. 
-// 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
 {
 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.
-// Account information.
+ * Stored in wallet with key "acc"+string account name.
-// Stored in wallet with key "acc"+string account name
+ */
-//
 class CAccount
 {
 public:
@@ -644,10 +640,9 @@ public:
 
 
 
-//
+/** Internal transfers.
-// Internal transfers.
+ * Database key is acentry<account><counter>.
-// Database key is acentry<account><counter>
+ */
-//
 class CAccountingEntry
 {
 public: