Proposal: Rename the current help command so it can be used to display command documentation

[st0012]

This proposal includes 3 changes:

1. Add documentation API to command classes. For example, if we want to have pry-style APIs:

   module ExtendCommand
     class Debug < Nop
       description "Load `debug` gem and starts a debugging session"
   
       banner <<~MSG
         Usage: debug
   
         This command loads the `debug` gem and start a debugging session at the current location.
         ....
       MSG
     end
   end

2. Rename the current help command (showing API documents) to something else, like doc

   • In pry, byebug and debug, the help command are all used for showing command documents. So I think it's better to align with them.

3. Support the new help command to list command documents:

   • help - list all available commands
     • If we follow what pry or byebug do, we only display commands' descriptions.
     • If we follow debug, we'll display full documentation for all commands. So in this case we won't need the description attribute.
     • Question: this means we'll be loading command classes by default. Is this a good reason to do that?
   • help <cmd> - display individual commands' full usage (banner).

Since this will be a breaking change (renaming a command), we'll need to bump the version that includes this feature to 2.0.

[k0kubun]

While the two of us are allowed to add/modify IRB commands by just reviewing each other's PR, renaming/replacing an existing command would probably not be considered the same kind of change. It'd be nice to file a ticket on Redmine if you want to land this feature as help.

[st0012]

I see. I'll first add something like cmd-help or commands before proposing the renaming.
But do you agree to eagerly load commands so we can store their documents and descriptions as attributes? The current lazy-load design was introduced since 0.9 but I didn't find the reason behind it.

[k0kubun]

I think there was a moment when starting irb CLI was very slow, which could be related to it. We even have a benchmark for it under ruby/ruby/benchmark (irb_exec or something like that), so you may try it with and without lazy load.

Though, I don't get why you can't maintain lazy load. You'd only need to lazily load everything when you need to show/generate docs.

[st0012]

Though, I don't get why you can't maintain lazy load. You'd only need to lazily load everything when you need to show/generate docs.

Because I didn't think about that 😅 Thanks for the idea 👍

[st0012]

I'm closing this for now as we already implemented the main functionality of this command. I'll open a separate issue for repurposing the help command.