From 7d83a1c5d69d7e93b4013cfa638f8e380a89f3cc Mon Sep 17 00:00:00 2001
From: "Dirk-Jan C. Binnema" <djcb@djcbsoftware.nl>
Date: Sat, 25 Jan 2020 11:51:38 +0200
Subject: [PATCH] server: improve command documentation output

required args come first, then alphabetic.
---
 lib/utils/mu-command-parser.hh | 22 ++++++++++++++++++++++
 mu/mu-cmd-server.cc            | 15 ++++++++-------
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/lib/utils/mu-command-parser.hh b/lib/utils/mu-command-parser.hh
index 7dc1a6dc..458e0313 100644
--- a/lib/utils/mu-command-parser.hh
+++ b/lib/utils/mu-command-parser.hh
@@ -25,6 +25,7 @@
 #include <stdexcept>
 #include <unordered_map>
 #include <functional>
+#include <algorithm>
 
 #include "utils/mu-error.hh"
 #include "utils/mu-sexp-parser.hh"
@@ -80,6 +81,27 @@ struct CommandInfo {
         const ArgMap      args;
         const std::string docstring;
         const Handler     handler;
+
+        /**
+         * Get a sorted list of argument names, for display. Required args come
+         * first, then alphabetical.
+         *
+         * @return vec with the sorted names.
+         */
+        std::vector<std::string> sorted_argnames() const { // sort args -- by required, then alphabetical.
+                std::vector<std::string> names;
+                for (auto&& arg: args)
+                        names.emplace_back(arg.first);
+                std::sort(names.begin(), names.end(), [&](const auto& name1, const auto& name2) {
+                        const auto& arg1{args.find(name1)->second};
+                        const auto& arg2{args.find(name2)->second};
+                        if (arg1.required != arg2.required)
+                                return arg1.required;
+                        else
+                                return name1 < name2;
+                });
+                return names;
+        }
 };
 /// All commands, mapping their name to information about them.
 using CommandMap = std::unordered_map<std::string, CommandInfo>;
diff --git a/mu/mu-cmd-server.cc b/mu/mu-cmd-server.cc
index 4e6ab761..5628a824 100644
--- a/mu/mu-cmd-server.cc
+++ b/mu/mu-cmd-server.cc
@@ -742,11 +742,12 @@ help_handler (Context& context, const Parameters& params)
                 if (!full)
                         continue;
 
-                for (auto&& arg: info.args) {
+                for (auto&& argname: info.sorted_argnames()) {
+                        const auto& arg{info.args.find(argname)};
                         std::cout << ";;        "
-                                  << format("%-17s  : %-22s ", arg.first.c_str(),
-                                            to_string(arg.second).c_str());
-                        std::cout << "  " << arg.second.docstring << "\n";
+                                  << format("%-17s  : %-24s ", arg->first.c_str(),
+                                            to_string(arg->second).c_str());
+                        std::cout << "  " << arg->second.docstring << "\n";
                 }
                 std::cout << ";;\n";
         }
@@ -1090,8 +1091,8 @@ make_command_map (Context& context)
 
       cmap.emplace("add",
                    CommandInfo{
-                           ArgMap{ {"path",    ArgInfo{Type::String, true, "message-path" }},
-                                   {"maildir", ArgInfo{Type::String, true, "maildir" }}},
+                           ArgMap{ {"path",    ArgInfo{Type::String, true, "file system path to the message" }},
+                                   {"maildir", ArgInfo{Type::String, true, "the maildir the where the message lives" }}},
                            "add a message to the store",
                            [&](const auto& params){add_handler(context, params);}});
 
@@ -1164,7 +1165,7 @@ make_command_map (Context& context)
                                    {"cleanup", ArgInfo{Type::Symbol, false,
                                                            "whether to remove stale messages from the store"}},
                                    {"lazy-check", ArgInfo{Type::Symbol, false,
-                                            "Whether to avoid indexing up-to-date directories"}}},
+                                            "whether to avoid indexing up-to-date directories"}}},
                            "scan maildir for new/updated/removed messages",
                            [&](const auto& params){index_handler(context, params);}});