From 8ac19edf674382a33a7ab0acd1bd71175dfe9556 Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Wed, 12 Feb 2014 09:02:09 +0000 Subject: [PATCH] Add a docstring to commands --- src/command_manager.cc | 8 ++- src/command_manager.hh | 3 + src/commands.cc | 145 +++++++++++++++++++++++++++++++---------- 3 files changed, 118 insertions(+), 38 deletions(-) diff --git a/src/command_manager.cc b/src/command_manager.cc index a37105d1..622ab60a 100644 --- a/src/command_manager.cc +++ b/src/command_manager.cc @@ -18,21 +18,23 @@ bool CommandManager::command_defined(const String& command_name) const void CommandManager::register_command(String command_name, Command command, + String docstring, ParameterDesc param_desc, CommandFlags flags, CommandCompleter completer) { - m_commands[command_name] = { std::move(command), std::move(param_desc), flags, std::move(completer) }; + m_commands[command_name] = { std::move(command), std::move(docstring), std::move(param_desc), flags, std::move(completer) }; } void CommandManager::register_commands(memoryview command_names, Command command, + String docstring, ParameterDesc param_desc, CommandFlags flags, CommandCompleter completer) { kak_assert(not command_names.empty()); - m_commands[command_names[0]] = { std::move(command), std::move(param_desc), flags, completer }; + m_commands[command_names[0]] = { std::move(command), std::move(docstring), std::move(param_desc), flags, completer }; for (size_t i = 1; i < command_names.size(); ++i) m_aliases[command_names[i]] = command_names[0]; } @@ -355,6 +357,8 @@ std::pair CommandManager::command_info(const String& command_lin return res; res.first = cmd->first; + if (not cmd->second.docstring.empty()) + res.second += cmd->second.docstring + "\n"; auto& switches = cmd->second.param_desc.switches; if (not switches.empty()) { diff --git a/src/command_manager.hh b/src/command_manager.hh index 09a4e222..c7dd2a49 100644 --- a/src/command_manager.hh +++ b/src/command_manager.hh @@ -72,11 +72,13 @@ public: bool command_defined(const String& command_name) const; void register_command(String command_name, Command command, + String docstring, ParameterDesc param_desc, CommandFlags flags = CommandFlags::None, CommandCompleter completer = CommandCompleter()); void register_commands(memoryview command_names, Command command, + String docstring, ParameterDesc param_desc, CommandFlags flags = CommandFlags::None, CommandCompleter completer = CommandCompleter()); @@ -88,6 +90,7 @@ private: struct CommandDescriptor { Command command; + String docstring; ParameterDesc param_desc; CommandFlags flags; CommandCompleter completer; diff --git a/src/commands.cc b/src/commands.cc index 5b8a9c92..e39bac81 100644 --- a/src/commands.cc +++ b/src/commands.cc @@ -90,6 +90,8 @@ static const ParameterDesc edit_params{ ParameterDesc::Flags::None, 1, 3 }; +static const char* edit_desc = "edit : open the given filename in a buffer"; + template void edit(const ParametersParser& parser, Context& context) { @@ -137,6 +139,8 @@ static const ParameterDesc write_params{ ParameterDesc::Flags::None, 0, 1 }; +static const char* write_desc = "write [filename]: write the current buffer to it's file or to [filename] if specified"; + void write_buffer(const ParametersParser& parser, Context& context) { Buffer& buffer = context.buffer(); @@ -155,6 +159,7 @@ static const ParameterDesc no_params{ ParameterDesc::Flags::None, 0, 0 }; +static const char* write_all_desc = "write all buffers that are associated to a file"; void write_all_buffers(const ParametersParser& parser, Context& context) { @@ -165,6 +170,8 @@ void write_all_buffers(const ParametersParser& parser, Context& context) } } +static const char* quit_desc = "quit current client, and the kakoune session if the client is the last (if not running in daemon mode)"; + template void quit(const ParametersParser& parser, Context& context) { @@ -193,6 +200,8 @@ void quit(const ParametersParser& parser, Context& context) throw client_removed{}; } +static const char* write_and_quit_desc = "write current buffer and quit current client"; + template void write_and_quit(const ParametersParser& parser, Context& context) { @@ -202,6 +211,8 @@ void write_and_quit(const ParametersParser& parser, Context& context) static const ParameterDesc single_name_params{ SwitchMap{}, ParameterDesc::Flags::None, 1, 1 }; +static const char* show_buffer_desc = "buffer : set buffer to edit in current client"; + void show_buffer(const ParametersParser& parser, Context& context) { Buffer& buffer = BufferManager::instance().get_buffer(parser[0]); @@ -216,6 +227,8 @@ void show_buffer(const ParametersParser& parser, Context& context) static const ParameterDesc single_opt_name_params{ SwitchMap{}, ParameterDesc::Flags::None, 0, 1 }; +static const char* delete_buffer_desc = "delbuf [name]: delete the current buffer or the buffer named if given"; + template void delete_buffer(const ParametersParser& parser, Context& context) { @@ -230,12 +243,16 @@ void delete_buffer(const ParametersParser& parser, Context& context) manager.delete_buffer(buffer); } +static const char* set_buffer_name_desc = "namebuf : change current buffer name"; + void set_buffer_name(const ParametersParser& parser, Context& context) { if (not context.buffer().set_name(parser[0])) throw runtime_error("unable to change buffer name to " + parser[0]); } +static const char* define_highlighter_desc = "defhl : define a new reusable highlighter"; + void define_highlighter(const ParametersParser& parser, Context& context) { const String& name = parser[0]; @@ -245,9 +262,11 @@ void define_highlighter(const ParametersParser& parser, Context& context) static const ParameterDesc add_highlighter_params{ SwitchMap{ { "group", { true, "add highlighter to named group" } }, { "def-group", { true, "add highlighter to reusable defined group" } } }, - ParameterDesc::Flags::None, 1 + ParameterDesc::Flags::SwitchesOnlyAtStart, 1 }; +static const char* add_highlighter_desc = "addhl ...: add an highlighter to current window"; + void add_highlighter(const ParametersParser& parser, Context& context) { HighlighterRegistry& registry = HighlighterRegistry::instance(); @@ -281,6 +300,8 @@ static const ParameterDesc rm_highlighter_params{ ParameterDesc::Flags::None, 1, 1 }; +static const char* rm_highlighter_desc = "rmhl : remove highlighter from current window"; + void rm_highlighter(const ParametersParser& parser, Context& context) { HighlighterGroup& window_hl = context.window().highlighters(); @@ -306,6 +327,8 @@ static const ParameterDesc add_hook_params{ SwitchMap{ { "id", { true, "set hook id" } } }, ParameterDesc::Flags::None, 4, 4 }; +static const char* add_hook_desc = "hook : add to be executed on hook in context"; + void add_hook(const ParametersParser& parser, Context& context) { // copy so that the lambda gets a copy as well @@ -324,6 +347,8 @@ static const ParameterDesc rm_hooks_params{ SwitchMap{}, ParameterDesc::Flags::None, 2, 2 }; +static const char* rm_hooks_desc = "rmhooks : remove all hooks that whose id is "; + void rm_hooks(const ParametersParser& parser, Context& context) { get_hook_manager(parser[0], context).remove_hooks(parser[1]); @@ -360,6 +385,8 @@ static const ParameterDesc define_command_params{ 2, 2 }; +static const char* define_command_desc = "def : define a command named corresponding to "; + void define_command(const ParametersParser& parser, Context& context) { auto begin = parser.begin(); @@ -430,7 +457,7 @@ void define_command(const ParametersParser& parser, Context& context) return Completions{ 0_byte, params[token_to_complete].length(), split(output, '\n') }; }; } - CommandManager::instance().register_command(cmd_name, cmd, desc, flags, completer); + CommandManager::instance().register_command(cmd_name, cmd, "", desc, flags, completer); } static const ParameterDesc echo_message_params{ @@ -438,6 +465,8 @@ static const ParameterDesc echo_message_params{ ParameterDesc::Flags::SwitchesOnlyAtStart }; +static const char* echo_message_desc = "echo ...: display given parameters in the status line"; + void echo_message(const ParametersParser& parser, Context& context) { String message; @@ -453,6 +482,8 @@ static const ParameterDesc write_debug_message_params{ ParameterDesc::Flags::SwitchesOnlyAtStart }; +static const char* write_debug_message_desc = "debug ...: write given parameters in the debug buffer"; + void write_debug_message(const ParametersParser& parser, Context&) { String message; @@ -467,6 +498,8 @@ static const ParameterDesc exec_commands_in_file_params{ 1, 1 }; +static const char* exec_commands_in_file_desc = "source : execute commands contained in "; + void exec_commands_in_file(const ParametersParser& parser, Context& context) { @@ -503,6 +536,8 @@ static const ParameterDesc set_option_params{ 3, 3 }; +static const char* set_option_desc = "set : set option in to "; + void set_option(const ParametersParser& parser, Context& context) { Option& opt = get_options(parser[0], context).get_local_option(parser[1]); @@ -518,6 +553,17 @@ static const ParameterDesc declare_option_params{ 2, 3 }; +static const char* declare_option_desc = +"decl [value]: declare option of type , with initial value if given\n" +"Available types:\n" +" int: integer\n" +" bool: boolean (true/false or yes/no)\n" +" str: character string\n" +" regex: regular expression\n" +" int-list: list of integers\n" +" str-list: list of character strings\n" +" line-flag-list: list of line flags\n"; + void declare_option(const ParametersParser& parser, Context& context) { Option* opt = nullptr; @@ -574,6 +620,14 @@ static const ParameterDesc map_key_params{ SwitchMap{}, ParameterDesc::Flags::None, 4, 4 }; +static const char* map_key_desc = +"map : map to in given mode.\n" +"Valid modes:\n" +" normal\n" +" insert\n" +" menu\n" +" prompt\n"; + void map_key(const ParametersParser& parser, Context& context) { KeymapManager& keymaps = get_keymap_manager(parser[0], context); @@ -643,6 +697,8 @@ void context_wrap(const ParametersParser& parser, Context& context, Func func) real_context->window().forget_timestamp(); } +static const char* exec_string_desc = "exec : execute given keys as if entered by user"; + void exec_string(const ParametersParser& parser, Context& context) { context_wrap(parser, context, [](const ParametersParser& parser, Context& context) { @@ -656,6 +712,8 @@ void exec_string(const ParametersParser& parser, Context& context) }); } +static const char* eval_string_desc = "eval : execute commands as if entered by user"; + void eval_string(const ParametersParser& parser, Context& context) { context_wrap(parser, context, [](const ParametersParser& parser, Context& context) { @@ -671,6 +729,9 @@ static const ParameterDesc menu_params{ { "select-cmds", { false, "each item specify an additional command to run when selected" } } } }; +static const char* menu_desc = "menu ...: display a menu and execute commands for the selected item"; + + void menu(const ParametersParser& parser, Context& context) { const bool with_select_cmds = parser.has_option("select-cmds"); @@ -712,6 +773,8 @@ static const ParameterDesc info_params{ ParameterDesc::Flags::None, 0, 1 }; +static const char* info_desc = "info ...: display an info box with the params as content"; + void info(const ParametersParser& parser, Context& context) { context.ui().info_hide(); @@ -743,6 +806,8 @@ static const ParameterDesc try_catch_params{ SwitchMap{}, ParameterDesc::Flags::None, 1, 3 }; +static const char* try_catch_desc = "try [catch ]: execute command in current context, and if an error is raised, execute if specified.\nThe error is not propagated further."; + void try_catch(const ParametersParser& parser, Context& context) { if (parser.positional_count() == 2) @@ -768,6 +833,8 @@ static const ParameterDesc define_color_alias_params{ SwitchMap{}, ParameterDesc::Flags::None, 2, 2 }; +static const char* define_color_alias_desc = "colalias : set to refer to color (which can be an alias itself)"; + void define_color_alias(const ParametersParser& parser, Context& context) { ColorRegistry::instance().register_alias(parser[0], parser[1], true); @@ -777,6 +844,8 @@ static const ParameterDesc set_client_name_params{ SwitchMap{}, ParameterDesc::Flags::None, 1, 1 }; +static const char* set_client_name_desc = "nameclient : set current client name to "; + void set_client_name(const ParametersParser& parser, Context& context) { if (ClientManager::instance().validate_client_name(parser[0])) @@ -789,6 +858,8 @@ static const ParameterDesc set_register_params{ SwitchMap{}, ParameterDesc::Flags::None, 2, 2 }; +static const char* set_register_desc = "reg : set register to "; + void set_register(const ParametersParser& parser, Context& context) { if (parser[0].length() != 1) @@ -800,6 +871,8 @@ static const ParameterDesc change_working_directory_params{ SwitchMap{}, ParameterDesc::Flags::None, 1, 1 }; +static const char* change_working_directory_desc = "cd : change server working directory to "; + void change_working_directory(const ParametersParser& parser, Context&) { if (chdir(parse_filename(parser[0]).c_str()) != 0) @@ -884,7 +957,7 @@ void register_commands() { CommandManager& cm = CommandManager::instance(); - cm.register_commands({"nop"}, [](const ParametersParser&, Context&){}, {}); + cm.register_commands({"nop"}, [](const ParametersParser&, Context&){}, "do nothing", {}); PerArgumentCommandCompleter filename_completer({ [](const Context& context, CompletionFlags flags, const String& prefix, ByteCount cursor_pos) @@ -893,31 +966,31 @@ void register_commands() context.options()["ignored_files"].get(), cursor_pos) }; } }); - cm.register_commands({ "edit", "e" }, edit, edit_params, CommandFlags::None, filename_completer); - cm.register_commands({ "edit!", "e!" }, edit, edit_params, CommandFlags::None, filename_completer); - cm.register_commands({ "write", "w" }, write_buffer, write_params, CommandFlags::None, filename_completer); - cm.register_commands({ "writeall", "wa" }, write_all_buffers, no_params); - cm.register_commands({ "quit", "q" }, quit, no_params); - cm.register_commands({ "quit!", "q!" }, quit, no_params); - cm.register_command("wq", write_and_quit, no_params); - cm.register_command("wq!", write_and_quit, no_params); + cm.register_commands({ "edit", "e" }, edit, edit_desc, edit_params, CommandFlags::None, filename_completer); + cm.register_commands({ "edit!", "e!" }, edit, edit_desc, edit_params, CommandFlags::None, filename_completer); + cm.register_commands({ "write", "w" }, write_buffer, write_desc, write_params, CommandFlags::None, filename_completer); + cm.register_commands({ "writeall", "wa" }, write_all_buffers, write_all_desc, no_params); + cm.register_commands({ "quit", "q" }, quit, quit_desc, no_params); + cm.register_commands({ "quit!", "q!" }, quit, quit_desc, no_params); + cm.register_command("wq", write_and_quit, write_and_quit_desc, no_params); + cm.register_command("wq!", write_and_quit, write_and_quit_desc, no_params); PerArgumentCommandCompleter buffer_completer({ [](const Context& context, CompletionFlags flags, const String& prefix, ByteCount cursor_pos) { return Completions{ 0_byte, prefix.length(), BufferManager::instance().complete_buffername(prefix, cursor_pos) }; } }); - cm.register_commands({ "buffer", "b" }, show_buffer, single_name_params, CommandFlags::None, buffer_completer); - cm.register_commands({ "delbuf", "db" }, delete_buffer, single_opt_name_params, CommandFlags::None, buffer_completer); - cm.register_commands({ "delbuf!", "db!" }, delete_buffer, single_opt_name_params, CommandFlags::None, buffer_completer); - cm.register_commands({ "namebuf", "nb" }, set_buffer_name, single_name_params); + cm.register_commands({ "buffer", "b" }, show_buffer, show_buffer_desc, single_name_params, CommandFlags::None, buffer_completer); + cm.register_commands({ "delbuf", "db" }, delete_buffer, delete_buffer_desc, single_opt_name_params, CommandFlags::None, buffer_completer); + cm.register_commands({ "delbuf!", "db!" }, delete_buffer, delete_buffer_desc, single_opt_name_params, CommandFlags::None, buffer_completer); + cm.register_commands({ "namebuf", "nb" }, set_buffer_name, set_buffer_name_desc, single_name_params); auto get_highlighters = [](const Context& c) -> HighlighterGroup& { return c.window().highlighters(); }; - cm.register_commands({ "addhl", "ah" }, add_highlighter, add_highlighter_params, CommandFlags::None, group_add_completer(get_highlighters)); - cm.register_commands({ "rmhl", "rh" }, rm_highlighter, rm_highlighter_params, CommandFlags::None, group_rm_completer(get_highlighters)); - cm.register_commands({ "defhl", "dh" }, define_highlighter, single_name_params); + cm.register_commands({ "addhl", "ah" }, add_highlighter, add_highlighter_desc, add_highlighter_params, CommandFlags::None, group_add_completer(get_highlighters)); + cm.register_commands({ "rmhl", "rh" }, rm_highlighter, rm_highlighter_desc, rm_highlighter_params, CommandFlags::None, group_rm_completer(get_highlighters)); + cm.register_commands({ "defhl", "dh" }, define_highlighter, define_highlighter_desc, single_name_params); - cm.register_command("hook", add_hook, add_hook_params, CommandFlags::None, + cm.register_command("hook", add_hook, add_hook_desc, add_hook_params, CommandFlags::None, [](const Context& context, CompletionFlags flags, CommandParameters params, size_t token_to_complete, ByteCount pos_in_token) { @@ -931,24 +1004,24 @@ void register_commands() } return Completions{}; }); - cm.register_command("rmhooks", rm_hooks, rm_hooks_params); + cm.register_command("rmhooks", rm_hooks, rm_hooks_desc, rm_hooks_params); - cm.register_command("source", exec_commands_in_file, exec_commands_in_file_params, CommandFlags::None, filename_completer); + cm.register_command("source", exec_commands_in_file, exec_commands_in_file_desc, exec_commands_in_file_params, CommandFlags::None, filename_completer); - cm.register_command("exec", exec_string, context_wrap_params); - cm.register_command("eval", eval_string, context_wrap_params); - cm.register_command("menu", menu, menu_params); - cm.register_command("info", info, info_params); - cm.register_command("try", try_catch, try_catch_params); - cm.register_command("reg", set_register, set_register_params); + cm.register_command("exec", exec_string, exec_string_desc, context_wrap_params); + cm.register_command("eval", eval_string, eval_string_desc, context_wrap_params); + cm.register_command("menu", menu, menu_desc, menu_params); + cm.register_command("info", info, info_desc, info_params); + cm.register_command("try", try_catch, try_catch_desc, try_catch_params); + cm.register_command("reg", set_register, set_register_desc, set_register_params); - cm.register_command("def", define_command, define_command_params); - cm.register_command("decl", declare_option, declare_option_params); + cm.register_command("def", define_command, define_command_desc, define_command_params); + cm.register_command("decl", declare_option, declare_option_desc, declare_option_params); - cm.register_command("echo", echo_message, echo_message_params); - cm.register_command("debug", write_debug_message, write_debug_message_params); + cm.register_command("echo", echo_message, echo_message_desc, echo_message_params); + cm.register_command("debug", write_debug_message, write_debug_message_desc, write_debug_message_params); - cm.register_command("set", set_option, set_option_params, CommandFlags::None, + cm.register_command("set", set_option, set_option_desc, set_option_params, CommandFlags::None, [](const Context& context, CompletionFlags, CommandParameters params, size_t token_to_complete, ByteCount pos_in_token) -> Completions @@ -965,10 +1038,10 @@ void register_commands() return Completions{}; } ); - cm.register_commands({ "colalias", "ca" }, define_color_alias, define_color_alias_params); - cm.register_commands({ "nameclient", "nc" }, set_client_name, set_client_name_params); + cm.register_commands({ "colalias", "ca" }, define_color_alias, define_color_alias_desc, define_color_alias_params); + cm.register_commands({ "nameclient", "nc" }, set_client_name, set_client_name_desc, set_client_name_params); - cm.register_command("cd", change_working_directory, change_working_directory_params, CommandFlags::None, filename_completer); - cm.register_command("map", map_key, map_key_params); + cm.register_command("cd", change_working_directory, change_working_directory_desc, change_working_directory_params, CommandFlags::None, filename_completer); + cm.register_command("map", map_key, map_key_desc, map_key_params); } }