From 72fb3d295ab14d7e6b876d709be23bae1289dab2 Mon Sep 17 00:00:00 2001
From: Michael Ford <fanquake@gmail.com>
Date: Thu, 20 Nov 2014 10:19:29 +0800
Subject: [PATCH] Update comments in src/rpc* to be doxygen compatible

---
 src/rpcblockchain.cpp     |  6 ++--
 src/rpcclient.cpp         | 10 +++---
 src/rpcclient.h           |  4 +--
 src/rpcdump.cpp           |  2 +-
 src/rpcmining.cpp         | 12 ++++---
 src/rpcmisc.cpp           | 10 +++---
 src/rpcnet.cpp            |  2 +-
 src/rpcprotocol.cpp       | 34 +++++++++---------
 src/rpcprotocol.h         | 72 +++++++++++++++++++--------------------
 src/rpcrawtransaction.cpp |  2 +-
 src/rpcserver.h           |  7 ++--
 src/rpcwallet.cpp         |  2 +-
 12 files changed, 83 insertions(+), 80 deletions(-)

diff --git a/src/rpcblockchain.cpp b/src/rpcblockchain.cpp
index a7cd63bd9..7919fb1a0 100644
--- a/src/rpcblockchain.cpp
+++ b/src/rpcblockchain.cpp
@@ -1,6 +1,6 @@
 // Copyright (c) 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.
 
 #include "checkpoints.h"
@@ -468,7 +468,7 @@ Value getblockchaininfo(const Array& params, bool fHelp)
     return obj;
 }
 
-/* Comparison function for sorting the getchaintips heads.  */
+/** Comparison function for sorting the getchaintips heads.  */
 struct CompareBlocksByHeight
 {
     bool operator()(const CBlockIndex* a, const CBlockIndex* b) const
diff --git a/src/rpcclient.cpp b/src/rpcclient.cpp
index 7a1f1918f..03ce9acbb 100644
--- a/src/rpcclient.cpp
+++ b/src/rpcclient.cpp
@@ -1,6 +1,6 @@
 // Copyright (c) 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.
 
 #include "rpcclient.h"
@@ -18,8 +18,8 @@ using namespace json_spirit;
 class CRPCConvertParam
 {
 public:
-    std::string methodName;            // method whose params want conversion
-    int paramIdx;                      // 0-based idx of param to convert
+    std::string methodName;            //! method whose params want conversion
+    int paramIdx;                      //! 0-based idx of param to convert
 };
 
 static const CRPCConvertParam vRPCConvertParams[] =
@@ -116,7 +116,7 @@ CRPCConvertTable::CRPCConvertTable()
 
 static CRPCConvertTable rpcCvtTable;
 
-// Convert strings to command-specific RPC representation
+/** Convert strings to command-specific RPC representation */
 Array RPCConvertValues(const std::string &strMethod, const std::vector<std::string> &strParams)
 {
     Array params;
diff --git a/src/rpcclient.h b/src/rpcclient.h
index cd11f177e..a91c2eb03 100644
--- a/src/rpcclient.h
+++ b/src/rpcclient.h
@@ -1,6 +1,6 @@
 // Copyright (c) 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.
 
 #ifndef BITCOIN_RPCCLIENT_H
diff --git a/src/rpcdump.cpp b/src/rpcdump.cpp
index 9da0a7d09..c3ffe38cc 100644
--- a/src/rpcdump.cpp
+++ b/src/rpcdump.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 "base58.h"
diff --git a/src/rpcmining.cpp b/src/rpcmining.cpp
index 2bde02c0a..81120ba98 100644
--- a/src/rpcmining.cpp
+++ b/src/rpcmining.cpp
@@ -1,6 +1,6 @@
 // Copyright (c) 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.
 
 #include "amount.h"
@@ -28,9 +28,11 @@
 using namespace json_spirit;
 using namespace std;
 
-// Return average network hashes per second based on the last 'lookup' blocks,
-// or from the last difficulty change if 'lookup' is nonpositive.
-// If 'height' is nonnegative, compute the estimate at the time when a given block was found.
+/**
+ * Return average network hashes per second based on the last 'lookup' blocks,
+ * or from the last difficulty change if 'lookup' is nonpositive.
+ * If 'height' is nonnegative, compute the estimate at the time when a given block was found.
+ */
 Value GetNetworkHashPS(int lookup, int height) {
     CBlockIndex *pb = chainActive.Tip();
 
diff --git a/src/rpcmisc.cpp b/src/rpcmisc.cpp
index 31eaae616..90b9c99ca 100644
--- a/src/rpcmisc.cpp
+++ b/src/rpcmisc.cpp
@@ -1,6 +1,6 @@
 // Copyright (c) 2010 Satoshi Nakamoto
 // 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 "base58.h"
@@ -30,7 +30,7 @@ using namespace std;
 
 /**
  * @note Do not add or change anything in the information returned by this
- * method. `getinfo` exists for backwards-compatibilty only. It combines
+ * method. `getinfo` exists for backwards-compatibility only. It combines
  * information from wildly different sources in the program, which is a mess,
  * and is thus planned to be deprecated eventually.
  *
@@ -198,9 +198,9 @@ Value validateaddress(const Array& params, bool fHelp)
     return ret;
 }
 
-//
-// Used by addmultisigaddress / createmultisig:
-//
+/**
+ * Used by addmultisigaddress / createmultisig:
+ */
 CScript _createmultisig_redeemScript(const Array& params)
 {
     int nRequired = params[0].get_int();
diff --git a/src/rpcnet.cpp b/src/rpcnet.cpp
index 46b5f3d7a..6ddbd62fc 100644
--- a/src/rpcnet.cpp
+++ b/src/rpcnet.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 "rpcserver.h"
diff --git a/src/rpcprotocol.cpp b/src/rpcprotocol.cpp
index c2ce73106..2f7c491f3 100644
--- a/src/rpcprotocol.cpp
+++ b/src/rpcprotocol.cpp
@@ -1,6 +1,6 @@
 // Copyright (c) 2010 Satoshi Nakamoto
 // 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 "rpcprotocol.h"
@@ -30,15 +30,15 @@ using namespace boost;
 using namespace boost::asio;
 using namespace json_spirit;
 
-// Number of bytes to allocate and read at most at once in post data
+//! Number of bytes to allocate and read at most at once in post data
 const size_t POST_READ_SIZE = 256 * 1024;
 
-//
-// HTTP protocol
-//
-// This ain't Apache.  We're just using HTTP header for the length field
-// and to be compatible with other JSON-RPC implementations.
-//
+/**
+ * HTTP protocol
+ * 
+ * This ain't Apache.  We're just using HTTP header for the length field
+ * and to be compatible with other JSON-RPC implementations.
+ */
 
 string HTTPPost(const string& strMsg, const map<string,string>& mapRequestHeaders)
 {
@@ -246,15 +246,15 @@ int ReadHTTPMessage(std::basic_istream<char>& stream, map<string,
     return HTTP_OK;
 }
 
-//
-// JSON-RPC protocol.  Bitcoin speaks version 1.0 for maximum compatibility,
-// but uses JSON-RPC 1.1/2.0 standards for parts of the 1.0 standard that were
-// unspecified (HTTP errors and contents of 'error').
-//
-// 1.0 spec: http://json-rpc.org/wiki/specification
-// 1.2 spec: http://jsonrpc.org/historical/json-rpc-over-http.html
-// http://www.codeproject.com/KB/recipes/JSON_Spirit.aspx
-//
+/**
+ * JSON-RPC protocol.  Bitcoin speaks version 1.0 for maximum compatibility,
+ * but uses JSON-RPC 1.1/2.0 standards for parts of the 1.0 standard that were
+ * unspecified (HTTP errors and contents of 'error').
+ * 
+ * 1.0 spec: http://json-rpc.org/wiki/specification
+ * 1.2 spec: http://jsonrpc.org/historical/json-rpc-over-http.html
+ * http://www.codeproject.com/KB/recipes/JSON_Spirit.aspx
+ */
 
 string JSONRPCRequest(const string& strMethod, const Array& params, const Value& id)
 {
diff --git a/src/rpcprotocol.h b/src/rpcprotocol.h
index f0d0f3445..a32133817 100644
--- a/src/rpcprotocol.h
+++ b/src/rpcprotocol.h
@@ -1,6 +1,6 @@
 // Copyright (c) 2010 Satoshi Nakamoto
 // 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.
 
 #ifndef BITCOIN_RPCPROTOCOL_H
@@ -19,7 +19,7 @@
 #include "json/json_spirit_utils.h"
 #include "json/json_spirit_writer_template.h"
 
-// HTTP status codes
+//! HTTP status codes
 enum HTTPStatusCode
 {
     HTTP_OK                    = 200,
@@ -30,56 +30,56 @@ enum HTTPStatusCode
     HTTP_INTERNAL_SERVER_ERROR = 500,
 };
 
-// Bitcoin RPC error codes
+//! Bitcoin RPC error codes
 enum RPCErrorCode
 {
-    // Standard JSON-RPC 2.0 errors
+    //! Standard JSON-RPC 2.0 errors
     RPC_INVALID_REQUEST  = -32600,
     RPC_METHOD_NOT_FOUND = -32601,
     RPC_INVALID_PARAMS   = -32602,
     RPC_INTERNAL_ERROR   = -32603,
     RPC_PARSE_ERROR      = -32700,
 
-    // General application defined errors
-    RPC_MISC_ERROR                  = -1,  // std::exception thrown in command handling
-    RPC_FORBIDDEN_BY_SAFE_MODE      = -2,  // Server is in safe mode, and command is not allowed in safe mode
-    RPC_TYPE_ERROR                  = -3,  // Unexpected type was passed as parameter
-    RPC_INVALID_ADDRESS_OR_KEY      = -5,  // Invalid address or key
-    RPC_OUT_OF_MEMORY               = -7,  // Ran out of memory during operation
-    RPC_INVALID_PARAMETER           = -8,  // Invalid, missing or duplicate parameter
-    RPC_DATABASE_ERROR              = -20, // Database error
-    RPC_DESERIALIZATION_ERROR       = -22, // Error parsing or validating structure in raw format
-    RPC_VERIFY_ERROR                = -25, // General error during transaction or block submission
-    RPC_VERIFY_REJECTED             = -26, // Transaction or block was rejected by network rules
-    RPC_VERIFY_ALREADY_IN_CHAIN     = -27, // Transaction already in chain
-    RPC_IN_WARMUP                   = -28, // Client still warming up
+    //! General application defined errors
+    RPC_MISC_ERROR                  = -1,  //! std::exception thrown in command handling
+    RPC_FORBIDDEN_BY_SAFE_MODE      = -2,  //! Server is in safe mode, and command is not allowed in safe mode
+    RPC_TYPE_ERROR                  = -3,  //! Unexpected type was passed as parameter
+    RPC_INVALID_ADDRESS_OR_KEY      = -5,  //! Invalid address or key
+    RPC_OUT_OF_MEMORY               = -7,  //! Ran out of memory during operation
+    RPC_INVALID_PARAMETER           = -8,  //! Invalid, missing or duplicate parameter
+    RPC_DATABASE_ERROR              = -20, //! Database error
+    RPC_DESERIALIZATION_ERROR       = -22, //! Error parsing or validating structure in raw format
+    RPC_VERIFY_ERROR                = -25, //! General error during transaction or block submission
+    RPC_VERIFY_REJECTED             = -26, //! Transaction or block was rejected by network rules
+    RPC_VERIFY_ALREADY_IN_CHAIN     = -27, //! Transaction already in chain
+    RPC_IN_WARMUP                   = -28, //! Client still warming up
 
-    // Aliases for backward compatibility
+    //! Aliases for backward compatibility
     RPC_TRANSACTION_ERROR           = RPC_VERIFY_ERROR,
     RPC_TRANSACTION_REJECTED        = RPC_VERIFY_REJECTED,
     RPC_TRANSACTION_ALREADY_IN_CHAIN= RPC_VERIFY_ALREADY_IN_CHAIN,
 
-    // P2P client errors
-    RPC_CLIENT_NOT_CONNECTED        = -9,  // Bitcoin is not connected
-    RPC_CLIENT_IN_INITIAL_DOWNLOAD  = -10, // Still downloading initial blocks
-    RPC_CLIENT_NODE_ALREADY_ADDED   = -23, // Node is already added
-    RPC_CLIENT_NODE_NOT_ADDED       = -24, // Node has not been added before
+    //! P2P client errors
+    RPC_CLIENT_NOT_CONNECTED        = -9,  //! Bitcoin is not connected
+    RPC_CLIENT_IN_INITIAL_DOWNLOAD  = -10, //! Still downloading initial blocks
+    RPC_CLIENT_NODE_ALREADY_ADDED   = -23, //! Node is already added
+    RPC_CLIENT_NODE_NOT_ADDED       = -24, //! Node has not been added before
 
-    // Wallet errors
-    RPC_WALLET_ERROR                = -4,  // Unspecified problem with wallet (key not found etc.)
-    RPC_WALLET_INSUFFICIENT_FUNDS   = -6,  // Not enough funds in wallet or account
-    RPC_WALLET_INVALID_ACCOUNT_NAME = -11, // Invalid account name
-    RPC_WALLET_KEYPOOL_RAN_OUT      = -12, // Keypool ran out, call keypoolrefill first
-    RPC_WALLET_UNLOCK_NEEDED        = -13, // Enter the wallet passphrase with walletpassphrase first
-    RPC_WALLET_PASSPHRASE_INCORRECT = -14, // The wallet passphrase entered was incorrect
-    RPC_WALLET_WRONG_ENC_STATE      = -15, // Command given in wrong wallet encryption state (encrypting an encrypted wallet etc.)
-    RPC_WALLET_ENCRYPTION_FAILED    = -16, // Failed to encrypt the wallet
-    RPC_WALLET_ALREADY_UNLOCKED     = -17, // Wallet is already unlocked
+    //! Wallet errors
+    RPC_WALLET_ERROR                = -4,  //! Unspecified problem with wallet (key not found etc.)
+    RPC_WALLET_INSUFFICIENT_FUNDS   = -6,  //! Not enough funds in wallet or account
+    RPC_WALLET_INVALID_ACCOUNT_NAME = -11, //! Invalid account name
+    RPC_WALLET_KEYPOOL_RAN_OUT      = -12, //! Keypool ran out, call keypoolrefill first
+    RPC_WALLET_UNLOCK_NEEDED        = -13, //! Enter the wallet passphrase with walletpassphrase first
+    RPC_WALLET_PASSPHRASE_INCORRECT = -14, //! The wallet passphrase entered was incorrect
+    RPC_WALLET_WRONG_ENC_STATE      = -15, //! Command given in wrong wallet encryption state (encrypting an encrypted wallet etc.)
+    RPC_WALLET_ENCRYPTION_FAILED    = -16, //! Failed to encrypt the wallet
+    RPC_WALLET_ALREADY_UNLOCKED     = -17, //! Wallet is already unlocked
 };
 
-//
-// IOStream device that speaks SSL but can also speak non-SSL
-//
+/**
+ * IOStream device that speaks SSL but can also speak non-SSL
+ */
 template <typename Protocol>
 class SSLIOStreamDevice : public boost::iostreams::device<boost::iostreams::bidirectional> {
 public:
diff --git a/src/rpcrawtransaction.cpp b/src/rpcrawtransaction.cpp
index d3ce3b319..25734f493 100644
--- a/src/rpcrawtransaction.cpp
+++ b/src/rpcrawtransaction.cpp
@@ -1,6 +1,6 @@
 // Copyright (c) 2010 Satoshi Nakamoto
 // 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 "base58.h"
diff --git a/src/rpcserver.h b/src/rpcserver.h
index b3234f65f..7395fc23c 100644
--- a/src/rpcserver.h
+++ b/src/rpcserver.h
@@ -40,12 +40,13 @@ void StartRPCThreads();
  * If real RPC threads have already been started this is a no-op.
  */
 void StartDummyRPCThread();
-/* Stop RPC threads */
+/** Stop RPC threads */
 void StopRPCThreads();
-/* Query whether RPC is running */
+/** Query whether RPC is running */
 bool IsRPCRunning();
 
-/* Set the RPC warmup status.  When this is done, all RPC calls will error out
+/** 
+ * Set the RPC warmup status.  When this is done, all RPC calls will error out
  * immediately with RPC_IN_WARMUP.
  */
 void SetRPCWarmupStatus(const std::string& newStatus);
diff --git a/src/rpcwallet.cpp b/src/rpcwallet.cpp
index 4d9e5ea13..d2d14ad9f 100644
--- a/src/rpcwallet.cpp
+++ b/src/rpcwallet.cpp
@@ -1,6 +1,6 @@
 // Copyright (c) 2010 Satoshi Nakamoto
 // 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 "amount.h"