search

sopel-irc / sopel-help

Help plugin for Sopel
Other
0 stars 1 forks source link

Subcommand-style callable enhancements #10

Open dgw opened 3 months ago

dgw commented 3 months ago

Sopel 8's documentation for @plugin.command suggests a couple different ways to do "subcommands", which can be pretty great. One way is to have .command sub1, .command sub2, ..., .command (the final definition providing a default action or showing usage) on a single callable, as proposed for .tmask in sopel-irc/sopel#2601. The implementation ends up pretty clean, with the only stylistic downside (IMO) being an extra level of indentation on the code to handle each subcommand. (In less trivial cases, each subcommand naturally lends itself to being a separate helper function anyway, so I don't think this is that big of a drawback in practice.)

However: I'm not super happy with the tools available to plugin authors for writing help to go with this style. The single callable naturally has only a single docstring, which can be confusingly long if it attempts to explain the full range of options available, which is made worse by the help plugin's naïve line-splitting:

16:29:20 <dgw> .help tmask
16:29:21 <SopelGitpod> Set, get, or clear the current channel's topic mask.
16:29:21 <SopelGitpod> Recognized subcommands are 'set', 'get', and 'clear'. A plain 'tmask'
16:29:21 <SopelGitpod> command with no arguments is equivalent to 'tmask get'.
16:29:23 <SopelGitpod> This mask is used by the 'topic' command. `{}` allows interpolating a chunk
16:29:24 <SopelGitpod> of text within the topic mask template.
16:29:25 <SopelGitpod> e.g. .tmask set My {} topic mask!, .tmask get or .tmask clear

At the moment, I'm afraid I don't have any concrete ideas for making this better. The goal right now is to simply recognize that it's a problem—if other people also think the above is clunky—and then we can brainstorm how to improve things independently of Sopel's release cycle because this plugin is separate now. 😸

dgw commented 3 months ago

Oh, and maybe the aforementioned line-splitting behavior should be its own issue? It should be possible now to detect paragraph breaks in callable docstrings and rewrap the text using the value from bot.safe_text_length(recipient) so it will fit in the minimum number of IRC lines instead of blindly following line breaks in the plugin's source code.