Merge #11191: RPC: Improve help text and behavior of RPC-logging.

Summary:
c60c49b Improve help text and behavior of RPC-logging (Akio Nakamura)

Pull request description:

  1. It is allowed `libevent` logging to be updated during runtime,
    but still described that restriction in the help text.
    So we delete these text.
  2. Add a descrption about the evaluation order of `<include>` and
    `<exclude>` to clarify how debug loggig categories to be set.
  3. Add a description about the available logging category `"all"`
    which is not explained.
  4. Add `"optional"` to the help text of `<include>` and `<exclude>`.
  5. Add missing new lines before `"Argument:"`.
  6. `"0"`,`"1"` are allowed in both array of `<include>` and `<exclude>`.
    `"0"` is **ignored** and `"1"` is treated **same as** `"all"`.
    It is confusing, so forbid them.
  7. It always returns all logging categories with status.
    Fix the help text to match this behavior.

Tree-SHA512: c2142da1a9bf714af8ebc38ac0d82394e2073fc0bd56f136372e3db7b2af3b6746f8d6b0241fe66c1698c208c124deb076be83f07dec0d0a180ad150593af415

Backport Core PR11191
bitcoin/bitcoin#11191

Depends on D3684

Test Plan:
  make check
  ./bitcoind
  ./bitcoin-cli help logging
Changes should be reflected in the help text

Reviewers: deadalnix, Fabien, jasonbcox, O1 Bitcoin ABC, #bitcoin_abc

Reviewed By: Fabien, O1 Bitcoin ABC, #bitcoin_abc

Differential Revision: https://reviews.bitcoinabc.org/D3699

src/init.cpp

@@ -1528,8 +1528,9 @@ bool AppInitParameterInteraction(Config &config) {
         // Special-case: if -debug=0/-nodebug is set, turn off debugging
         // messages
         const std::vector<std::string> &categories = gArgs.GetArgs("-debug");
-        if (find(categories.begin(), categories.end(), std::string("0")) ==
-            categories.end()) {
+        if (std::none_of(
+                categories.begin(), categories.end(),
+                [](std::string cat) { return cat == "0" || cat == "none"; })) {
             for (const auto &cat : categories) {
                 BCLog::LogFlags flag = BCLog::NONE;
                 if (!GetLogCategory(flag, cat)) {

src/rpc/misc.cpp

@@ -420,25 +420,43 @@ static void EnableOrDisableLogCategories(UniValue cats, bool enable) {
 static UniValue logging(const Config &config, 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"
+            "with status that are currently being debug logged or not.\n"
             "When called with arguments, adds or removes categories from debug "
-            "logging.\n"
+            "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.\n"
-            "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"
+            "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"
-            "<categories>  (string): a list of the logging categories that are "
-            "active.\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]\""));