From 6c65c5e080d381bb713172976847baad5650e24b Mon Sep 17 00:00:00 2001
From: Maxime Coste <frrrwww@gmail.com>
Date: Thu, 19 Feb 2015 13:54:03 +0000
Subject: [PATCH] Add docstrings to highlighters, displayed by addhl help

---
 src/commands.cc     | 14 +++++++--
 src/highlighter.hh  |  8 ++++-
 src/highlighters.cc | 71 +++++++++++++++++++++++++++++++++++++--------
 src/string.cc       | 14 +++++++++
 src/string.hh       |  2 ++
 5 files changed, 94 insertions(+), 15 deletions(-)

diff --git a/src/commands.cc b/src/commands.cc
index d4039e33..f271a2fc 100644
--- a/src/commands.cc
+++ b/src/commands.cc
@@ -505,7 +505,17 @@ const CommandDesc add_highlighter_cmd = {
         SwitchMap{ { "group", { true, "specify the group in which to put the highlighter" } } },
         ParameterDesc::Flags::SwitchesOnlyAtStart, 1 },
     CommandFlags::None,
-    CommandHelper{},
+    [](const Context& context, CommandParameters params) -> String
+    {
+        if (params.size() > 0)
+        {
+            HighlighterRegistry& registry = HighlighterRegistry::instance();
+            auto it = registry.find(params[0]);
+            if (it != registry.end())
+                return params[0] + ":\n" + indent(it->second.docstring);
+        }
+        return "";
+    },
     add_highlighter_completer,
     [](const ParametersParser& parser, Context& context)
     {
@@ -523,7 +533,7 @@ const CommandDesc add_highlighter_cmd = {
         auto it = registry.find(name);
         if (it == registry.end())
             throw runtime_error("No such highlighter factory '" + name + "'");
-        group.add_child(it->second(highlighter_params));
+        group.add_child(it->second.factory(highlighter_params));
     }
 };
 
diff --git a/src/highlighter.hh b/src/highlighter.hh
index 028d4b2c..9a5463af 100644
--- a/src/highlighter.hh
+++ b/src/highlighter.hh
@@ -67,7 +67,13 @@ std::unique_ptr<SimpleHighlighter<T>> make_simple_highlighter(T func)
 using HighlighterParameters = ArrayView<String>;
 using HighlighterFactory = std::function<HighlighterAndId (HighlighterParameters params)>;
 
-struct HighlighterRegistry : IdMap<HighlighterFactory>,
+struct HighlighterFactoryAndDocstring
+{
+    HighlighterFactory factory;
+    String docstring;
+};
+
+struct HighlighterRegistry : IdMap<HighlighterFactoryAndDocstring>,
                              Singleton<HighlighterRegistry>
 {};
 
diff --git a/src/highlighters.cc b/src/highlighters.cc
index 17f6fb14..2bf031cd 100644
--- a/src/highlighters.cc
+++ b/src/highlighters.cc
@@ -1205,18 +1205,65 @@ void register_highlighters()
 {
     HighlighterRegistry& registry = HighlighterRegistry::instance();
 
-    registry.append({ "number_lines", simple_factory("number_lines", show_line_numbers) });
-    registry.append({ "show_matching", simple_factory("show_matching", show_matching_char) });
-    registry.append({ "show_whitespaces", simple_factory("show_whitespaces", show_whitespaces) });
-    registry.append({ "fill", create_fill_highlighter });
-    registry.append({ "regex", RegexHighlighter::create });
-    registry.append({ "regex_option", create_regex_option_highlighter });
-    registry.append({ "search", create_search_highlighter });
-    registry.append({ "group", create_highlighter_group });
-    registry.append({ "flag_lines", create_flag_lines_highlighter });
-    registry.append({ "line_option", create_line_option_highlighter });
-    registry.append({ "ref", create_reference_highlighter });
-    registry.append({ "regions", RegionsHighlighter::create });
+    registry.append({
+        "number_lines",
+        { simple_factory("number_lines", show_line_numbers),
+          "Display line numbers" } });
+    registry.append({
+        "show_matching",
+        { simple_factory("show_matching", show_matching_char),
+          "Apply the MatchingChar face to the char matching the one under the cursor" } });
+    registry.append({
+        "show_whitespaces",
+        { simple_factory("show_whitespaces", show_whitespaces),
+          "Display whitespaces using symbols" } });
+    registry.append({
+        "fill",
+        { create_fill_highlighter,
+          "Fill the whole highlighted range with the given face" } });
+    registry.append({
+        "regex",
+        { RegexHighlighter::create,
+          "Parameters: <regex> <capture num>:<face> <capture num>:<face>...\n"
+          "Highlights the matches for captures from the regex with the given faces" } });
+    registry.append({
+        "regex_option",
+        { create_regex_option_highlighter,
+          "Parameters: <option name> <face>\n"
+          "Highlight matches for the regex stored in <option name> with <face>" } });
+    registry.append({
+        "search",
+        { create_search_highlighter,
+          "Highlight the current search pattern with the Search face" } });
+    registry.append({
+        "group",
+        { create_highlighter_group,
+          "Parameters: <group name>\n"
+          "Creates a named group that can contain other highlighters" } });
+    registry.append({
+        "flag_lines",
+        { create_flag_lines_highlighter,
+          "Parameters: <option name> <bg color>\n"
+          "Display flags specified in the line-flag-list option <option name>\n"
+          "A line-flag is written: <line>|<fg color>|<text>, the list is : separated" } });
+    registry.append({
+        "line_option",
+        { create_line_option_highlighter,
+          "Parameters: <option name> <face>\n"
+          "Highlight the line stored in <option name> with <face>" } });
+    registry.append({
+        "ref",
+        { create_reference_highlighter,
+          "Parameters: <path>\n"
+          "Reference the highlighter at <path> in shared highglighters" } });
+    registry.append({
+        "regions",
+        { RegionsHighlighter::create,
+          "Parameters: [-default <default group>] {<name> <begin> <end> <recurse>}..."
+          "Split the highlighting into regions defined by the <begin>, <end> and <recurse> regex\n"
+          "The region <name> starts at <begin> match, end at <end> match that does not\n"
+          "close a <recurse> match. In between region is the <default group>.\n"
+          "Highlighting a region is done by adding highlighters into the different <name> subgroups." } });
 }
 
 }
diff --git a/src/string.cc b/src/string.cc
index db2a7e21..beeb4a74 100644
--- a/src/string.cc
+++ b/src/string.cc
@@ -86,6 +86,20 @@ String unescape(StringView str, StringView characters, char escape)
     return res;
 }
 
+String indent(StringView str, StringView indent)
+{
+    String res;
+    bool was_eol = true;
+    for (ByteCount i = 0; i < str.length(); ++i)
+    {
+        if (was_eol)
+            res += indent;
+        res += str[i];
+        was_eol = is_eol(str[i]);
+    }
+    return res;
+}
+
 int str_to_int(StringView str)
 {
     int res = 0;
diff --git a/src/string.hh b/src/string.hh
index 7166c8b3..74df3fd7 100644
--- a/src/string.hh
+++ b/src/string.hh
@@ -246,6 +246,8 @@ Vector<StringView> split(StringView str, char separator);
 String escape(StringView str, StringView characters, char escape);
 String unescape(StringView str, StringView characters, char escape);
 
+String indent(StringView str, StringView indent = "    ");
+
 template<typename Container>
 String join(const Container& container, char joiner, bool esc_joiner = true)
 {