Improve help text and behavior of RPC-logging

A) The changes in behavior are as follows:
1. Introduce logging category "none" as alias of "0" for
   both RPC-logging and bitcoind "-debug" parameter.
2. Same as "0" is given to argument of "-debug",
   if "none" or "0" is given to <include>, all other given logging
   categories are ignored. The same is true for <exclude>.
   (Before this PR, "0" was accepted but just be ignored itself.)

B) The changes in the help text are as follows:
1. Add a descrption about the evaluation order of <include> and
   <exclude> to clarify how debug loggig categories to be set.
2. Delete text that describe restriction about libevent because
   it's already allowed libevent logging to be updated during runtime.
3. Add a description for category "all", "1", "none" and "0".
4. Add "optional" to the help text of <include> and <exclude>.
5. Add missing new lines before "Argument:".
6. This RPC always returns all logging categories with status.
   Fix the help text to match this behavior.

1 files changed, 27 insertions, 8 deletions

diff --git a/src/rpc/misc.cpp b/src/rpc/misc.cpp
index a6af24f7e1..0a5508016f 100644
--- a/src/rpc/misc.cpp
+++ b/src/rpc/misc.cpp
@@ -577,6 +577,9 @@ uint32_t getCategoryMask(UniValue cats) {
         if (!GetLogCategory(&flag, &cat)) {
             throw JSONRPCError(RPC_INVALID_PARAMETER, "unknown logging category " + cat);
         }
+        if (flag == BCLog::NONE) {
+            return 0;
+        }
         mask |= flag;
     }
     return mask;
@@ -586,16 +589,32 @@ UniValue logging(const JSONRPCRequest& request)
 {
     if (request.fHelp || request.params.size() > 2) {
         throw std::runtime_error(
-            "logging [include,...] <exclude>\n"
+            "logging ( <include> <exclude> )\n"
             "Gets and sets the logging configuration.\n"
-            "When called without an argument, returns the list of categories that are currently being debug logged.\n"
-            "When called with arguments, adds or removes categories from debug logging.\n"
+            "When called without an argument, returns the list of categories with status that are currently being debug logged or not.\n"
+            "When called with arguments, adds or removes categories from debug logging and return the lists above.\n"
+            "The arguments are evaluated in order \"include\", \"exclude\".\n"
+            "If an item is both included and excluded, it will thus end up being excluded.\n"
             "The valid logging categories are: " + ListLogCategories() + "\n"
-            "libevent logging is configured on startup and cannot be modified by this RPC during runtime."
-            "Arguments:\n"
-            "1. \"include\" (array of strings) add debug logging for these categories.\n"
-            "2. \"exclude\" (array of strings) remove debug logging for these categories.\n"
-            "\nResult: <categories>  (string): a list of the logging categories that are active.\n"
+            "In addition, the following are available as category names with special meanings:\n"
+            "  - \"all\",  \"1\" : represent all logging categories.\n"
+            "  - \"none\", \"0\" : even if other logging categories are specified, ignore all of them.\n"
+            "\nArguments:\n"
+            "1. \"include\"        (array of strings, optional) A json array of categories to add debug logging\n"
+            "     [\n"
+            "       \"category\"   (string) the valid logging category\n"
+            "       ,...\n"
+            "     ]\n"
+            "2. \"exclude\"        (array of strings, optional) A json array of categories to remove debug logging\n"
+            "     [\n"
+            "       \"category\"   (string) the valid logging category\n"
+            "       ,...\n"
+            "     ]\n"
+            "\nResult:\n"
+            "{                   (json object where keys are the logging categories, and values indicates its status\n"
+            "  \"category\": 0|1,  (numeric) if being debug logged or not. 0:inactive, 1:active\n"
+            "  ...\n"
+            "}\n"
             "\nExamples:\n"
             + HelpExampleCli("logging", "\"[\\\"all\\\"]\" \"[\\\"http\\\"]\"")
             + HelpExampleRpc("logging", "[\"all\"], \"[libevent]\"")