slack-machine
slack-machine copied to clipboard
Overhaul help texts
Help texts for plugin functions are currently defined using docstrings and shown through the built-in help plugin. There are several problems with this approach:
- One function can be decorated with multiple listeners, which might require different help texts (e.g. the same function can be triggered by different "commands")
- With the inclusion of new ways to interact - such as slash commands introduced in #787 - help texts will probably look different for these different interactions. There is no way to capture this in one universal docstring format
- We're relying on an unstructured docstring to parse different parts of the help text. For example in
@listen_to
and@respond_to
, the help text consists of the command itself that triggers the function, separated by a colon from the description. It would be better not to rely on text parsing
Proposal: help texts are generated on a per-decorator basis. Each decorator contains a help
argument for passing in the help text, which is sent to Slack as-is, augmented with metadata depending on the type of interaction (e.g. for slash commands, the actual slash command can prefix the rest of the help text)