From a6099ef319a73e2255dca77065600abb22c4f5f8 Mon Sep 17 00:00:00 2001 From: sje Date: Tue, 29 Oct 2013 22:29:44 +1100 Subject: Issue #1865 - Clean up RPC help messages Based on the proposal, update the help message of rpc methods - strings arguments are in double quotes rather than square brackets - numeric arguments have no quotes (and no default value) - optional parameters are surrounded by round brackets - json arguments are strings but don't use double quotes Added 3 sections for the details - Arguments: lists each argument, it's type, required or not, a default, and a description - Result: The method result, with json format if applicable, type, and a description - Examples: examples calls using bitcoin-cli and curl for json rpc call Problems - maybe this is too verbose - lines might be too long - description are not good or complete - examples may be too much --- src/rpcnet.cpp | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 89 insertions(+), 11 deletions(-) (limited to 'src/rpcnet.cpp') diff --git a/src/rpcnet.cpp b/src/rpcnet.cpp index 4885758395..9f8dea80b0 100644 --- a/src/rpcnet.cpp +++ b/src/rpcnet.cpp @@ -24,7 +24,13 @@ Value getconnectioncount(const Array& params, bool fHelp) if (fHelp || params.size() != 0) throw runtime_error( "getconnectioncount\n" - "Returns the number of connections to other nodes."); + "\nReturns the number of connections to other nodes.\n" + "\nbResult:\n" + "n (numeric) The connection count\n" + "\nExamples:\n" + + HelpExampleCli("getconnectioncount", "") + + HelpExampleRpc("getconnectioncount", "") + ); LOCK(cs_vNodes); return (int)vNodes.size(); @@ -35,9 +41,13 @@ Value ping(const Array& params, bool fHelp) if (fHelp || params.size() != 0) throw runtime_error( "ping\n" - "Requests that a ping be sent to all other nodes, to measure ping time.\n" + "\nRequests that a ping be sent to all other nodes, to measure ping time.\n" "Results provided in getpeerinfo, pingtime and pingwait fields are decimal seconds.\n" - "Ping command is handled in queue with all other commands, so it measures processing backlog, not just network ping."); + "Ping command is handled in queue with all other commands, so it measures processing backlog, not just network ping." + "\nExamples:\n" + + HelpExampleCli("ping", "") + + HelpExampleRpc("ping", "") + ); // Request that each node send a ping during next message processing pass LOCK(cs_vNodes); @@ -66,7 +76,34 @@ Value getpeerinfo(const Array& params, bool fHelp) if (fHelp || params.size() != 0) throw runtime_error( "getpeerinfo\n" - "Returns data about each connected network node."); + "\nReturns data about each connected network node as a json array of objects.\n" + "\nbResult:\n" + "[\n" + " {\n" + " \"addr\":\"host:port\", (string) The ip address and port of the peer\n" + " \"addrlocal\":\"ip:port\", (string) local address\n" + " \"services\":\"00000001\", (string) The services\n" + " \"lastsend\": ttt, (numeric) The time in seconds since epoch (Jan 1 1970 GMT) of the last send\n" + " \"lastrecv\": ttt, (numeric) The time in seconds since epoch (Jan 1 1970 GMT) of the last receive\n" + " \"bytessent\": n, (numeric) The total bytes sent\n" + " \"bytesrecv\": n, (numeric) The total bytes received\n" + " \"conntime\": ttt, (numeric) The connection time in seconds since epoch (Jan 1 1970 GMT)\n" + " \"pingtime\": n, (numeric) ping time\n" + " \"pingwait\": n, (numeric) ping wait\n" + " \"version\": v, (numeric) The peer version, such as 7001\n" + " \"subver\": \"/Satoshi:0.8.5/\", (string) The string version\n" + " \"inbound\": true|false, (boolean) Inbound (true) or Outbound (false)\n" + " \"startingheight\": n, (numeric) The starting height (block) of the peer\n" + " \"banscore\": n, (numeric) The ban score (stats.nMisbehavior)\n" + " \"syncnode\" : true|false (booleamn) if sync node\n" + " }\n" + " ,...\n" + "}\n" + + "\nExamples:\n" + + HelpExampleCli("getpeerinfo", "") + + HelpExampleRpc("getpeerinfo", "") + ); vector vstats; CopyNodeStats(vstats); @@ -110,8 +147,16 @@ Value addnode(const Array& params, bool fHelp) if (fHelp || params.size() != 2 || (strCommand != "onetry" && strCommand != "add" && strCommand != "remove")) throw runtime_error( - "addnode \n" - "Attempts add or remove from the addnode list or try a connection to once."); + "addnode \"node\" \"add|remove|onetry\"\n" + "\nAttempts add or remove a node from the addnode list.\n" + "Or try a connection to a node once.\n" + "\nArguments:\n" + "1. \"node\" (string, required) The node (see getpeerinfo for nodes)\n" + "2. \"command\" (string, required) 'add' to add a node to the list, 'remove' to remove a node from the list, 'onetry' to try a connection to the node once\n" + "\nExamples:\n" + + HelpExampleCli("addnode", "\"192.168.0.6:8333\" \"onetry\"") + + HelpExampleRpc("addnode", "\"192.168.0.6:8333\", \"onetry\"") + ); string strNode = params[0].get_str(); @@ -148,11 +193,34 @@ Value getaddednodeinfo(const Array& params, bool fHelp) { if (fHelp || params.size() < 1 || params.size() > 2) throw runtime_error( - "getaddednodeinfo [node]\n" - "Returns information about the given added node, or all added nodes\n" + "getaddednodeinfo dns ( \"node\" )\n" + "\nReturns information about the given added node, or all added nodes\n" "(note that onetry addnodes are not listed here)\n" "If dns is false, only a list of added nodes will be provided,\n" - "otherwise connected information will also be available."); + "otherwise connected information will also be available.\n" + "\nArguments:\n" + "1. dns (boolean, required) If false, only a list of added nodes will be provided, otherwise connected information will also be available.\n" + "2. \"node\" (string, optional) If provided, return information about this specific node, otherwise all nodes are returned.\n" + "\nResult:\n" + "[\n" + " {\n" + " \"addednode\" : \"192.168.0.201\", (string) The node ip address\n" + " \"connected\" : true|false, (boolean) If connected\n" + " \"addresses\" : [\n" + " {\n" + " \"address\" : \"192.168.0.201:8333\", (string) The bitcoin server host and port\n" + " \"connected\" : \"outbound\" (string) connection, inbound or outbound\n" + " }\n" + " ,...\n" + " ]\n" + " }\n" + " ,...\n" + "]\n" + "\nExamples:\n" + + HelpExampleCli("getaddednodeinfo", "true") + + HelpExampleCli("getaddednodeinfo", "true \"192.168.0.201\"") + + HelpExampleRpc("getaddednodeinfo", "true, \"192.168.0.201\"") + ); bool fDns = params[0].get_bool(); @@ -241,8 +309,18 @@ Value getnettotals(const Array& params, bool fHelp) if (fHelp || params.size() > 0) throw runtime_error( "getnettotals\n" - "Returns information about network traffic, including bytes in, bytes out,\n" - "and current time."); + "\nReturns information about network traffic, including bytes in, bytes out,\n" + "and current time.\n" + "\nResult:\n" + "{\n" + " \"totalbytesrecv\": n, (numeric) Total bytes received\n" + " \"totalbytessent\": n, (numeric) Total Bytes sent\n" + " \"timemillis\": t (numeric) Total cpu time\n" + "}\n" + "\nExamples:\n" + + HelpExampleCli("getnettotals", "") + + HelpExampleRpc("getnettotals", "") + ); Object obj; obj.push_back(Pair("totalbytesrecv", static_cast< boost::uint64_t>(CNode::GetTotalBytesRecv()))); -- cgit v1.2.3