Skip to content

Commit 194aa6c

Browse files
laanwjlaanwj
committed
Merge pull request #3246 from laanwj/2013_11_rpc_help
Clean up RPC help messages (rebased)
2 parents 2830a90 + a6099ef commit 194aa6c

File tree

8 files changed

+1350
-196
lines changed

8 files changed

+1350
-196
lines changed

‎src/bitcoinrpc.cpp

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -189,8 +189,13 @@ Value help(const Array& params, bool fHelp)
189189
{
190190
if (fHelp || params.size() > 1)
191191
throw runtime_error(
192-
"help [command]\n"
193-
"List commands, or get help for a command.");
192+
"help ( \"command\" )\n"
193+
"\nList all commands, or get help for a specified command.\n"
194+
"\nArguments:\n"
195+
"1. \"command\" (string, optional) The command to get help on\n"
196+
"\nResult:\n"
197+
"\"text\" (string) The help text\n"
198+
);
194199

195200
string strCommand;
196201
if (params.size() > 0)
@@ -206,7 +211,7 @@ Value stop(const Array& params, bool fHelp)
206211
if (fHelp || params.size() > 1)
207212
throw runtime_error(
208213
"stop\n"
209-
"Stop Bitcoin server.");
214+
"\nStop Bitcoin server.");
210215
// Shutdown will take long enough that the response should get back
211216
StartShutdown();
212217
return "Bitcoin server stopping";

‎src/bitcoinrpc.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,9 @@ extern json_spirit::Value ValueFromAmount(int64_t amount);
153153
extern double GetDifficulty(const CBlockIndex* blockindex = NULL);
154154
extern std::string HexBits(unsigned int nBits);
155155
extern std::string HelpRequiringPassphrase();
156+
extern std::string HelpExampleCli(std::string methodname, std::string args);
157+
extern std::string HelpExampleRpc(std::string methodname, std::string args);
158+
156159
extern void EnsureWalletIsUnlocked();
157160

158161
extern json_spirit::Value getconnectioncount(const json_spirit::Array& params, bool fHelp); // in rpcnet.cpp

‎src/rpcblockchain.cpp

Lines changed: 141 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,13 @@ Value getblockcount(const Array& params, bool fHelp)
8585
if (fHelp || params.size() != 0)
8686
throw runtime_error(
8787
"getblockcount\n"
88-
"Returns the number of blocks in the longest block chain.");
88+
"\nReturns the number of blocks in the longest block chain.\n"
89+
"\nResult:\n"
90+
"n (numeric) The current block count\n"
91+
"\nExamples:\n"
92+
+ HelpExampleCli("getblockcount", "")
93+
+ HelpExampleRpc("getblockcount", "")
94+
);
8995

9096
return chainActive.Height();
9197
}
@@ -95,7 +101,13 @@ Value getbestblockhash(const Array& params, bool fHelp)
95101
if (fHelp || params.size() != 0)
96102
throw runtime_error(
97103
"getbestblockhash\n"
98-
"Returns the hash of the best (tip) block in the longest block chain.");
104+
"\nReturns the hash of the best (tip) block in the longest block chain.\n"
105+
"\nResult\n"
106+
"\"hex\" (string) the block hash hex encoded\n"
107+
"\nExamples\n"
108+
+ HelpExampleCli("getbestblockhash", "")
109+
+ HelpExampleRpc("getbestblockhash", "")
110+
);
99111

100112
return chainActive.Tip()->GetBlockHash().GetHex();
101113
}
@@ -105,7 +117,13 @@ Value getdifficulty(const Array& params, bool fHelp)
105117
if (fHelp || params.size() != 0)
106118
throw runtime_error(
107119
"getdifficulty\n"
108-
"Returns the proof-of-work difficulty as a multiple of the minimum difficulty.");
120+
"\nReturns the proof-of-work difficulty as a multiple of the minimum difficulty.\n"
121+
"\nResult:\n"
122+
"n.nnn (numeric) the proof-of-work difficulty as a multiple of the minimum difficulty.\n"
123+
"\nExamples:\n"
124+
+ HelpExampleCli("getdifficulty", "")
125+
+ HelpExampleRpc("getdifficulty", "")
126+
);
109127

110128
return GetDifficulty();
111129
}
@@ -115,8 +133,16 @@ Value settxfee(const Array& params, bool fHelp)
115133
{
116134
if (fHelp || params.size() < 1 || params.size() > 1)
117135
throw runtime_error(
118-
"settxfee <amount btc/kb>\n"
119-
"<amount> is a real and is rounded to the nearest 0.00000001 btc per kb");
136+
"settxfee amount\n"
137+
"\nSet the transaction fee. 'amount' is a real and is rounded to the nearest 0.00000001\n"
138+
"\nArguments:\n"
139+
"1. amount (numeric, required) The transaction fee in btc rounded to the nearest 0.00000001\n"
140+
"\nResult\n"
141+
"true|false (boolean) Returns true if successful\n"
142+
"\nExamples:\n"
143+
+ HelpExampleCli("settxfee", "0.00001")
144+
+ HelpExampleRpc("settxfee", "0.00001")
145+
);
120146

121147
// Amount
122148
int64_t nAmount = 0;
@@ -132,7 +158,16 @@ Value getrawmempool(const Array& params, bool fHelp)
132158
if (fHelp || params.size() != 0)
133159
throw runtime_error(
134160
"getrawmempool\n"
135-
"Returns all transaction ids in memory pool.");
161+
"\nReturns all transaction ids in memory pool as a json array of string transaction ids.\n"
162+
"\nResult:\n"
163+
"[ (json array of string)\n"
164+
" \"transactionid\" (string) The transaction id\n"
165+
" ,...\n"
166+
"]\n"
167+
"\nExamples\n"
168+
+ HelpExampleCli("getrawmempool", "")
169+
+ HelpExampleRpc("getrawmempool", "")
170+
);
136171

137172
vector<uint256> vtxid;
138173
mempool.queryHashes(vtxid);
@@ -148,8 +183,16 @@ Value getblockhash(const Array& params, bool fHelp)
148183
{
149184
if (fHelp || params.size() != 1)
150185
throw runtime_error(
151-
"getblockhash <index>\n"
152-
"Returns hash of block in best-block-chain at <index>.");
186+
"getblockhash index\n"
187+
"\nReturns hash of block in best-block-chain at index provided.\n"
188+
"\nArguments:\n"
189+
"1. index (numeric, required) The block index\n"
190+
"\nResult:\n"
191+
"\"hash\" (string) The block hash\n"
192+
"\nExamples:\n"
193+
+ HelpExampleCli("getblockhash", "1000")
194+
+ HelpExampleRpc("getblockhash", "1000")
195+
);
153196

154197
int nHeight = params[0].get_int();
155198
if (nHeight < 0 || nHeight > chainActive.Height())
@@ -163,9 +206,36 @@ Value getblock(const Array& params, bool fHelp)
163206
{
164207
if (fHelp || params.size() < 1 || params.size() > 2)
165208
throw runtime_error(
166-
"getblock <hash> [verbose=true]\n"
167-
"If verbose is false, returns a string that is serialized, hex-encoded data for block <hash>.\n"
168-
"If verbose is true, returns an Object with information about block <hash>."
209+
"getblock \"hash\" ( verbose )\n"
210+
"\nIf verbose is false, returns a string that is serialized, hex-encoded data for block 'hash'.\n"
211+
"If verbose is true, returns an Object with information about block <hash>.\n"
212+
"\nArguments:\n"
213+
"1. \"hash\" (string, required) The block hash\n"
214+
"2. verbose (boolean, optional, default=true) true for a json object, false for the hex encoded data\n"
215+
"\nResult (for verbose = true):\n"
216+
"{\n"
217+
" \"hash\" : \"hash\", (string) the block hash (same as provided)\n"
218+
" \"confirmations\" : n, (numeric) The number of confirmations\n"
219+
" \"size\" : n, (numeric) The block size\n"
220+
" \"height\" : n, (numeric) The block height or index\n"
221+
" \"version\" : n, (numeric) The block version\n"
222+
" \"merkleroot\" : \"xxxx\", (string) The merkle root\n"
223+
" \"tx\" : [ (array of string) The transaction ids\n"
224+
" \"transactionid\" (string) The transaction id\n"
225+
" ,...\n"
226+
" ],\n"
227+
" \"time\" : ttt, (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)\n"
228+
" \"nonce\" : n, (numeric) The nonce\n"
229+
" \"bits\" : \"1d00ffff\", (string) The bits\n"
230+
" \"difficulty\" : x.xxx, (numeric) The difficulty\n"
231+
" \"previousblockhash\" : \"hash\", (string) The hash of the previous block\n"
232+
" \"nextblockhash\" : \"hash\" (string) The hash of the next block\n"
233+
"}\n"
234+
"\nResult (for verbose=false):\n"
235+
"\"data\" (string) A string that is serialized, hex-encoded data for block 'hash'.\n"
236+
"\nExamples:\n"
237+
+ HelpExampleCli("getblock", "\"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\"")
238+
+ HelpExampleRpc("getblock", "\"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\"")
169239
);
170240

171241
std::string strHash = params[0].get_str();
@@ -198,7 +268,22 @@ Value gettxoutsetinfo(const Array& params, bool fHelp)
198268
if (fHelp || params.size() != 0)
199269
throw runtime_error(
200270
"gettxoutsetinfo\n"
201-
"Returns statistics about the unspent transaction output set.");
271+
"\nReturns statistics about the unspent transaction output set.\n"
272+
"Note this call may take some time.\n"
273+
"\nResult:\n"
274+
"{\n"
275+
" \"height\":n, (numeric) The current block height (index)\n"
276+
" \"bestblock\": \"hex\", (string) the best block hash hex\n"
277+
" \"transactions\": n, (numeric) The number of transactions\n"
278+
" \"txouts\": n, (numeric) The number of output transactions\n"
279+
" \"bytes_serialized\": n, (numeric) The serialized size\n"
280+
" \"hash_serialized\": \"hash\", (string) The serialized hash\n"
281+
" \"total_amount\": x.xxx (numeric) The total amount\n"
282+
"}\n"
283+
"\nExamples:\n"
284+
+ HelpExampleCli("gettxoutsetinfo", "")
285+
+ HelpExampleRpc("gettxoutsetinfo", "")
286+
);
202287

203288
Object ret;
204289

@@ -219,8 +304,39 @@ Value gettxout(const Array& params, bool fHelp)
219304
{
220305
if (fHelp || params.size() < 2 || params.size() > 3)
221306
throw runtime_error(
222-
"gettxout <txid> <n> [includemempool=true]\n"
223-
"Returns details about an unspent transaction output.");
307+
"gettxout \"txid\" n ( includemempool )\n"
308+
"\nReturns details about an unspent transaction output.\n"
309+
"\nArguments:\n"
310+
"1. \"txid\" (string, required) The transaction id\n"
311+
"2. n (numeric, required) vout value\n"
312+
"3. includemempool (boolean, optional) Whether to included the mem pool\n"
313+
"\nResult:\n"
314+
"{\n"
315+
" \"bestblock\" : \"hash\", (string) the block hash\n"
316+
" \"confirmations\" : n, (numeric) The number of confirmations\n"
317+
" \"value\" : x.xxx, (numeric) The transaction value in btc\n"
318+
" \"scriptPubKey\" : { (json object)\n"
319+
" \"asm\" : \"code\", (string) \n"
320+
" \"hex\" : \"hex\", (string) \n"
321+
" \"reqSigs\" : n, (numeric) Number of required signatures\n"
322+
" \"type\" : \"pubkeyhash\", (string) The type, eg pubkeyhash\n"
323+
" \"addresses\" : [ (array of string) array of bitcoin addresses\n"
324+
" \"bitcoinaddress\" (string) bitcoin address\n"
325+
" ,...\n"
326+
" ]\n"
327+
" },\n"
328+
" \"version\" : n, (numeric) The version\n"
329+
" \"coinbase\" : true|false (boolean) Coinbase or not\n"
330+
"}\n"
331+
332+
"\nExamples:\n"
333+
"\nGet unspent transactions\n"
334+
+ HelpExampleCli("listunspent", "") +
335+
"\nView the details\n"
336+
+ HelpExampleCli("gettxout", "\"txid\" 1") +
337+
"\nAs a json rpc call\n"
338+
+ HelpExampleRpc("gettxout", "\"txid\", 1")
339+
);
224340

225341
Object ret;
226342

@@ -266,8 +382,17 @@ Value verifychain(const Array& params, bool fHelp)
266382
{
267383
if (fHelp || params.size() > 2)
268384
throw runtime_error(
269-
"verifychain [check level] [num blocks]\n"
270-
"Verifies blockchain database.");
385+
"verifychain ( checklevel numblocks )\n"
386+
"\nVerifies blockchain database.\n"
387+
"\nArguments:\n"
388+
"1. checklevel (numeric, optional, default=3) The level\n"
389+
"2. numblocks (numeric, optional, 288) The number of blocks\n"
390+
"\nResult:\n"
391+
"true|false (boolean) Verified or not\n"
392+
"\nExamples:\n"
393+
+ HelpExampleCli("verifychain", "")
394+
+ HelpExampleRpc("verifychain", "")
395+
);
271396

272397
int nCheckLevel = GetArg("-checklevel", 3);
273398
int nCheckDepth = GetArg("-checkblocks", 288);

‎src/rpcdump.cpp

Lines changed: 48 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,22 @@ Value importprivkey(const Array& params, bool fHelp)
7171
{
7272
if (fHelp || params.size() < 1 || params.size() > 3)
7373
throw runtime_error(
74-
"importprivkey <bitcoinprivkey> [label] [rescan=true]\n"
75-
"Adds a private key (as returned by dumpprivkey) to your wallet.");
74+
"importprivkey \"bitcoinprivkey\" ( \"label\" rescan )\n"
75+
"\nAdds a private key (as returned by dumpprivkey) to your wallet.\n"
76+
"\nArguments:\n"
77+
"1. \"bitcoinprivkey\" (string, required) The private key (see dumpprivkey)\n"
78+
"2. \"label\" (string, optional) an optional label\n"
79+
"3. rescan (boolean, optional, default=true) Rescan the wallet for transactions\n"
80+
"\nExamples:\n"
81+
"\nDump a private key\n"
82+
+ HelpExampleCli("dumpprivkey", "\"myaddress\"") +
83+
"\nImport the private key\n"
84+
+ HelpExampleCli("importprivkey", "\"mykey\"") +
85+
"\nImport using a label\n"
86+
+ HelpExampleCli("importprivkey", "\"mykey\" \"testing\" false") +
87+
"\nAs a json rpc call\n"
88+
+ HelpExampleRpc("importprivkey", "\"mykey\", \"testing\", false")
89+
);
7690

7791
string strSecret = params[0].get_str();
7892
string strLabel = "";
@@ -118,8 +132,18 @@ Value importwallet(const Array& params, bool fHelp)
118132
{
119133
if (fHelp || params.size() != 1)
120134
throw runtime_error(
121-
"importwallet <filename>\n"
122-
"Imports keys from a wallet dump file (see dumpwallet).");
135+
"importwallet \"filename\"\n"
136+
"\nImports keys from a wallet dump file (see dumpwallet).\n"
137+
"\nArguments:\n"
138+
"1. \"filename\" (string, required) The wallet file\n"
139+
"\nExamples:\n"
140+
"\nDump the wallet\n"
141+
+ HelpExampleCli("dumpwallet", "\"test\"") +
142+
"\nImport the wallet\n"
143+
+ HelpExampleCli("importwallet", "\"test\"") +
144+
"\nImport using the json rpc call\n"
145+
+ HelpExampleRpc("importwallet", "\"test\"")
146+
);
123147

124148
EnsureWalletIsUnlocked();
125149

@@ -198,8 +222,18 @@ Value dumpprivkey(const Array& params, bool fHelp)
198222
{
199223
if (fHelp || params.size() != 1)
200224
throw runtime_error(
201-
"dumpprivkey <bitcoinaddress>\n"
202-
"Reveals the private key corresponding to <bitcoinaddress>.");
225+
"dumpprivkey \"bitcoinaddress\"\n"
226+
"\nReveals the private key corresponding to 'bitcoinaddress'.\n"
227+
"Then the importprivkey can be used with this output\n"
228+
"\nArguments:\n"
229+
"1. \"bitcoinaddress\" (string, required) The bitcoin address for the private key\n"
230+
"\nResult:\n"
231+
"\"key\" (string) The private key\n"
232+
"\nExamples:\n"
233+
+ HelpExampleCli("dumpprivkey", "\"myaddress\"")
234+
+ HelpExampleCli("importprivkey", "\"mykey\"")
235+
+ HelpExampleRpc("dumpprivkey", "\"myaddress\"")
236+
);
203237

204238
EnsureWalletIsUnlocked();
205239

@@ -221,8 +255,14 @@ Value dumpwallet(const Array& params, bool fHelp)
221255
{
222256
if (fHelp || params.size() != 1)
223257
throw runtime_error(
224-
"dumpwallet <filename>\n"
225-
"Dumps all wallet keys in a human-readable format.");
258+
"dumpwallet \"filename\"\n"
259+
"\nDumps all wallet keys in a human-readable format.\n"
260+
"\nArguments:\n"
261+
"1. \"filename\" (string, required) The filename\n"
262+
"\nExamples:\n"
263+
+ HelpExampleCli("dumpwallet", "\"test\"")
264+
+ HelpExampleRpc("dumpwallet", "\"test\"")
265+
);
226266

227267
EnsureWalletIsUnlocked();
228268

0 commit comments

Comments
 (0)