Merge #18346: rpc: Document an RPCResult for all calls; Enforce at compile time

fac52253f81a4f0d04b25eb4b6c28d04b85ef10b rpc: Document an RPCResult for all calls; Enforce at compile time (MarcoFalke)
fadd99f61032c0b75ad9b198eb5d8e307b0518ee rpc: Add missing newline in RPCResult description (MarcoFalke)

Pull request description:

  This documents the RPC Result (type and description, if applicable) everywhere it was missing. The patch can be reviewed with the `git diff` option `-W`/`--function-context`.

  Also, code won't compile without having an RPCResult documented.

ACKs for top commit:
  laanwj:
    Lightly tested ACK fac52253f81a4f0d04b25eb4b6c28d04b85ef10b
  promag:
    Tested ACK fac52253f81a4f0d04b25eb4b6c28d04b85ef10b, built and verified listunspent help output.

Tree-SHA512: af2c1af1432beb944993776026c320814bfaecaf202f47359f5758849096ca7051ec6560395a2cc6678dcc111e7c9cf4917d0f0b221bdcf3ed1642e14d0e5b3c

6 files changed, 28 insertions, 23 deletions

diff --git a/src/rpc/blockchain.cpp b/src/rpc/blockchain.cpp
index 737ffc7664..256876a3d1 100644
--- a/src/rpc/blockchain.cpp
+++ b/src/rpc/blockchain.cpp
@@ -345,7 +345,7 @@ static UniValue syncwithvalidationinterfacequeue(const JSONRPCRequest& request)
             RPCHelpMan{"syncwithvalidationinterfacequeue",
                 "\nWaits for the validation interface queue to catch up on everything that was there when we entered this function.\n",
                 {},
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("syncwithvalidationinterfacequeue","")
             + HelpExampleRpc("syncwithvalidationinterfacequeue","")
@@ -1435,7 +1435,7 @@ static UniValue preciousblock(const JSONRPCRequest& request)
                 {
                     {"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hash of the block to mark as precious"},
                 },
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("preciousblock", "\"blockhash\"")
             + HelpExampleRpc("preciousblock", "\"blockhash\"")
@@ -1470,7 +1470,7 @@ static UniValue invalidateblock(const JSONRPCRequest& request)
                 {
                     {"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hash of the block to mark as invalid"},
                 },
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("invalidateblock", "\"blockhash\"")
             + HelpExampleRpc("invalidateblock", "\"blockhash\"")
@@ -1509,7 +1509,7 @@ static UniValue reconsiderblock(const JSONRPCRequest& request)
                 {
                     {"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hash of the block to reconsider"},
                 },
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("reconsiderblock", "\"blockhash\"")
             + HelpExampleRpc("reconsiderblock", "\"blockhash\"")
@@ -1933,7 +1933,7 @@ static UniValue savemempool(const JSONRPCRequest& request)
             RPCHelpMan{"savemempool",
                 "\nDumps the mempool to disk. It will fail until the previous dump is fully loaded.\n",
                 {},
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("savemempool", "")
             + HelpExampleRpc("savemempool", "")
diff --git a/src/rpc/mining.cpp b/src/rpc/mining.cpp
index 92440488a4..1bbb5c4bee 100644
--- a/src/rpc/mining.cpp
+++ b/src/rpc/mining.cpp
@@ -751,7 +751,7 @@ static UniValue submitblock(const JSONRPCRequest& request)
                     {"hexdata", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hex-encoded block data to submit"},
                     {"dummy", RPCArg::Type::STR, /* default */ "ignored", "dummy value, for compatibility with BIP22. This value is ignored."},
                 },
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", "Returns JSON Null when valid, a string according to BIP22 otherwise"},
                 RPCExamples{
                     HelpExampleCli("submitblock", "\"mydata\"")
             + HelpExampleRpc("submitblock", "\"mydata\"")
diff --git a/src/rpc/misc.cpp b/src/rpc/misc.cpp
index 4b16dd21a0..c87c1a5418 100644
--- a/src/rpc/misc.cpp
+++ b/src/rpc/misc.cpp
@@ -347,7 +347,7 @@ static UniValue setmocktime(const JSONRPCRequest& request)
                     {"timestamp", RPCArg::Type::NUM, RPCArg::Optional::NO, UNIX_EPOCH_TIME + "\n"
             "   Pass 0 to go back to using the system time."},
                 },
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{""},
             }.Check(request);
 
@@ -375,7 +375,7 @@ static UniValue mockscheduler(const JSONRPCRequest& request)
         {
             {"delta_time", RPCArg::Type::NUM, RPCArg::Optional::NO, "Number of seconds to forward the scheduler into the future." },
         },
-        RPCResults{},
+        RPCResult{RPCResult::Type::NONE, "", ""},
         RPCExamples{""},
     }.Check(request);
 
@@ -579,7 +579,7 @@ static UniValue echo(const JSONRPCRequest& request)
                 "\nThe difference between echo and echojson is that echojson has argument conversion enabled in the client-side table in "
                 "bitcoin-cli and the GUI. There is no server-side difference.",
                 {},
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", "Returns whatever was passed in"},
                 RPCExamples{""},
             }.ToString()
         );
diff --git a/src/rpc/net.cpp b/src/rpc/net.cpp
index eeb617f849..e26ca1b07a 100644
--- a/src/rpc/net.cpp
+++ b/src/rpc/net.cpp
@@ -54,7 +54,7 @@ static UniValue ping(const JSONRPCRequest& request)
                 "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.\n",
                 {},
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("ping", "")
             + HelpExampleRpc("ping", "")
@@ -240,7 +240,7 @@ static UniValue addnode(const JSONRPCRequest& request)
                     {"node", RPCArg::Type::STR, RPCArg::Optional::NO, "The node (see getpeerinfo for nodes)"},
                     {"command", RPCArg::Type::STR, RPCArg::Optional::NO, "'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"},
                 },
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("addnode", "\"192.168.0.6:8333\" \"onetry\"")
             + HelpExampleRpc("addnode", "\"192.168.0.6:8333\", \"onetry\"")
@@ -283,7 +283,7 @@ static UniValue disconnectnode(const JSONRPCRequest& request)
                     {"address", RPCArg::Type::STR, /* default */ "fallback to nodeid", "The IP address/port of the node"},
                     {"nodeid", RPCArg::Type::NUM, /* default */ "fallback to address", "The node ID (see getpeerinfo for node IDs)"},
                 },
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("disconnectnode", "\"192.168.0.6:8333\"")
             + HelpExampleCli("disconnectnode", "\"\" 1")
@@ -553,7 +553,7 @@ static UniValue setban(const JSONRPCRequest& request)
                     {"bantime", RPCArg::Type::NUM, /* default */ "0", "time in seconds how long (or until when if [absolute] is set) the IP is banned (0 or empty means using the default time of 24h which can also be overwritten by the -bantime startup argument)"},
                     {"absolute", RPCArg::Type::BOOL, /* default */ "false", "If set, the bantime must be an absolute timestamp expressed in " + UNIX_EPOCH_TIME},
                 },
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("setban", "\"192.168.0.6\" \"add\" 86400")
                             + HelpExampleCli("setban", "\"192.168.0.0/24\" \"add\"")
@@ -628,7 +628,16 @@ static UniValue listbanned(const JSONRPCRequest& request)
             RPCHelpMan{"listbanned",
                 "\nList all banned IPs/Subnets.\n",
                 {},
-                RPCResults{},
+        RPCResult{RPCResult::Type::ARR, "", "",
+            {
+                {RPCResult::Type::OBJ, "", "",
+                    {
+                        {RPCResult::Type::STR, "address", ""},
+                        {RPCResult::Type::NUM_TIME, "banned_until", ""},
+                        {RPCResult::Type::NUM_TIME, "ban_created", ""},
+                        {RPCResult::Type::STR, "ban_reason", ""},
+                    }},
+            }},
                 RPCExamples{
                     HelpExampleCli("listbanned", "")
                             + HelpExampleRpc("listbanned", "")
@@ -663,7 +672,7 @@ static UniValue clearbanned(const JSONRPCRequest& request)
             RPCHelpMan{"clearbanned",
                 "\nClear all banned IPs.\n",
                 {},
-                RPCResults{},
+                RPCResult{RPCResult::Type::NONE, "", ""},
                 RPCExamples{
                     HelpExampleCli("clearbanned", "")
                             + HelpExampleRpc("clearbanned", "")
@@ -685,7 +694,7 @@ static UniValue setnetworkactive(const JSONRPCRequest& request)
                 {
                     {"state", RPCArg::Type::BOOL, RPCArg::Optional::NO, "true to enable networking, false to disable"},
                 },
-                RPCResults{},
+                RPCResult{RPCResult::Type::BOOL, "", "The value that was passed in"},
                 RPCExamples{""},
             }.Check(request);
 
diff --git a/src/rpc/server.cpp b/src/rpc/server.cpp
index 2893aa0e60..e2618c16da 100644
--- a/src/rpc/server.cpp
+++ b/src/rpc/server.cpp
@@ -153,6 +153,7 @@ UniValue help(const JSONRPCRequest& jsonRequest)
 
 UniValue stop(const JSONRPCRequest& jsonRequest)
 {
+    static const std::string RESULT{PACKAGE_NAME " stopping"};
     // Accept the deprecated and ignored 'detach' boolean argument
     // Also accept the hidden 'wait' integer argument (milliseconds)
     // For instance, 'stop 1000' makes the call wait 1 second before returning
@@ -162,7 +163,7 @@ UniValue stop(const JSONRPCRequest& jsonRequest)
             RPCHelpMan{"stop",
                 "\nRequest a graceful shutdown of " PACKAGE_NAME ".",
                 {},
-                RPCResults{},
+                RPCResult{RPCResult::Type::STR, "", "A string with the content '" + RESULT + "'"},
                 RPCExamples{""},
             }.ToString());
     // Event loop will exit after current HTTP requests have been handled, so
@@ -171,7 +172,7 @@ UniValue stop(const JSONRPCRequest& jsonRequest)
     if (jsonRequest.params[0].isNum()) {
         UninterruptibleSleep(std::chrono::milliseconds{jsonRequest.params[0].get_int()});
     }
-    return PACKAGE_NAME " stopping";
+    return RESULT;
 }
 
 static UniValue uptime(const JSONRPCRequest& jsonRequest)
diff --git a/src/rpc/util.h b/src/rpc/util.h
index 5813df507f..f65ad1246b 100644
--- a/src/rpc/util.h
+++ b/src/rpc/util.h
@@ -290,11 +290,6 @@ struct RPCResult {
 struct RPCResults {
     const std::vector<RPCResult> m_results;
 
-    RPCResults()
-        : m_results{}
-    {
-    }
-
     RPCResults(RPCResult result)
         : m_results{{result}}
     {