Add chat command help for every single parameter

[Wuzzy2]

Problem

Sometimes, the single-line chat command description alone is not enough. In complex cases, you also want to have a precise description of what each parameter does (including value range) but the single description line would get too cluttered if all info is dumped into that. There are many builtin commands which aren't fully documented because of that (e.g. difference between full and quick for clearobjects).

Solution

To the chat command definition, add an optional field params_description. This is a table which contains tables. The inner tables are of the form {param, description}, in which param is the name of the parameter (as shown in params) and description is the description for that specific parameter. Both fields are user-readable and translation is allowed. The order in which the inner tables are defined will be the display order, with the first table on top. params_description may be nil, in which Minetest behaves as before.

There are several conventions that the documentation should introduce, in order to prevent mods from going all over the place with this:

• It should dictate that this table must be in the same order as the params are specified in the params syntax.
• For the inner param, the same syntax rules as for the params help applies, e.g. a variable parameter must be written like <radius> while a word that must be written verbatim like full. The "optionality" brackets have to be removed.

Rendering: /help all -t will remain unchanged. Only description is shown. But in /help <cmd> as well as the full help formspec, the description is shown as well as a list of params_description, printed in the correct order. Also, the parameters should be printed in a different color.

Example

Definition example:

minetest.register_chatcommand("shutdown", {
  description = "Shutdown server",
  params = "shutdown [<delay>] [-r] [<message>]",
  params_description = {
    {"<delay>", "Shutdown delay in seconds (default: 0). -1 aborts shutdown"},
    {"-r", "Allow players to reconnect"},
    {"<message>", "Shutdown message (none by default)"},
  },

   -- << insert other definition stuff here >>
})

How the help could be printed when entering /help shutdown:

/shutdown [<delay>] [-r] [<message>]: Shutdown server
* <delay>: Shutdown delay in seconds (default 0). -1 aborts shutdown
* -r: Allow players to reconnect
* <message>: Message sent to players on shutdown

[Desour]

:+1: One line is not enough for describing parameters.

I could also think of an alternative, more general, solution:

```lua minetest.register_chatcommand("shutdown", { description = "Shutdown server", params = "shutdown [] [-r] [] []", help_sections = { {"Description", -- section title "Some long text.", -- list of paragraphs "It has several paragraphs.", {"", "Shutdown delay in seconds (default: 0). -1 aborts shutdown."}, -- and rows (item and paragraph) {"-r", "Allow players to reconnect."}, {"", "Shutdown message (none by default)."}, {"", "Text. Names of things, like *shutdown* or ** should be made bold, btw., if possible. Also long lines should be wrapped."}, }, {"Notes", "Some text."}, -- one paragraph }, -- << insert other definition stuff here >> }) ``` This can then be formatted similar to man pages: ``` Name shutdown - Shutdown server Synopsis /shutdown [] [-r] [] [] Description Some long text. It has several paragraphs. Shutdown delay in seconds (default 0). -1 aborts shutdown. -r Allow players to reconnect. Message sent to players on shutdown. Text. Names of things, like shutdown or should be made bold, btw., if possible. Also long lines should be wrapped. Notes Some Text. ```

[wsor4035]

seems like something a mod can easily do, is there a reason the engine needs to do this?

[Wuzzy2]

I specifically went for a parameter list instead of completely freeform so the data is more structured and parsable. With freeform text you don't have that benefit. Also, I don't really know of an use case for very generic notes. If you need that, your command is probably too complicated anyway and needs simplification / refactoring / etc. But there is a strong use case for a specific parameter description, even for builtin. I don't like the full freeform approach and I don't think it is needed.

Also, this cannot be done by mods without massive hackery. The /help is handled by builtin. Also the /help dialog.

[wsor4035]

so the tldr is you want this in the engine, even though it can be done by a mod

Also, this cannot be done by mods without massive hackery. this is false, its no different than mods overriding any other part of things the engine does

[Wuzzy2]

And how would you implement that in a mod without compability nightmares?

[wsor4035]

ten minutes to write a proof of concept (just to prove it can be done)

local helpfunc = minetest.registered_chatcommands["help"].func

--add wuzzy example
minetest.override_chatcommand("shutdown", {
    description = "shutdown server",
    params = "shutdown [<delay>] [-r] [<message>]",
    params_description = {
        {"<delay>", "Shutdown delay in seconds (default: 0). -1 aborts shutdown"},
        {"-r", "Allow players to reconnect"},
        {"<message>", "Shutdown message (none by default)"},
    },
})

minetest.override_chatcommand("help", {
    func = function(name, param)
        local params = param:split(" ")
        if #params==1 and minetest.registered_chatcommands[params[1]] then
            local bool, text = helpfunc(name, param)
            if(minetest.registered_chatcommands[params[1]].params_description) then
                for _, v in pairs(minetest.registered_chatcommands[params[1]].params_description) do
                    text = text .. "\n* " .. v[1] .. ": " .. v[2]
                end
            end
            return bool, text
        else
            return helpfunc(name, param)
        end
    end
})

in game screenshot

wuzzy example output (for comparison)

/shutdown [<delay>] [-r] [<message>]: Shutdown server
* <delay>: Shutdown delay in seconds (default 0). -1 aborts shutdown
* -r: Allow players to reconnect
* <message>: Message sent to players on shutdown

[Wuzzy2]

Just because it can be done theoretically in mods does not mean it's a good idea. Also, you forgot the help formspec. :P

It feels wrong you need an external mod to add proper documentation for the builtin chatcommands.

[wsor4035]

ill flip it on the head for you

Just because it can be done theoretically in mods does not mean it's a good idea.

just because it can be done in the engine does not mean its a good idea

also, i didnt forget about the help formspec, your implementation list a chat command response in the original message, and to my limited testing, /help command_name just returns a chat message

[Wuzzy2]

Reasons why this should be in engine/builtin/core:

• The only logical place to improve the documentation of builtin commands is builtin (and there are quite a number of builtin commands which kinda have an incomplete documentation right now)
• Documenting chat command parameters is a no-brainer feature. There is no logical reason why a game should not want this
• Every mod and game can instantly benefit from this and don't have to worry about interoperability

Reasons why this should not be done by mods:

• We will end up with multiple, competing implementations (NIH syndrome) ...
• ... which in turn leads to inconsistencies and potential depencency hell
• Also, only if you depend on these mods you can potentially benefit from the added documentation. Modders are very allergic to dependencies of this kind
• Adding documentation of builtin commands in mods is a terrible idea. What if there's multiple mods? You'll have multiple contradicting unofficial documentations! What if they become outdated? Bad, bad, bad idea. Put documentation where it belongs
• Overwriting builtin features is risky and you might potentially lose forwards-compability. What if the official builtin implementation changes?
• It doesn't seem there is any real benefit from 3rd party implementations; they will boil down to do more or less the same stuff, just slightly different in an incompatible manner

[SmallJoker]

It's an optional feature for mods to provide a better user experience by providing more helpful in-game help.

Concept :+1: from my side for sure.