Please add documentation on how subcommands work

[dacid44]

It appears that subcommands (specifically for slash commands, using the command macro in my case) are somehow implemented, but the only times I can see them mentioned in the documentation (on the page for the command macro and the page for the Command struct, and not how to use them.

I can infer from compiler error messages that when specified in the command macro, subcommands should be the name of another function, and have worked out that:

• As far as I can tell, it doesn't matter what you put into the parent command function, as long as it accepts the required Context parameter and returns the Result that is expected by the macro. It doesn't appear the parent command ever gets run by running a subcommand, it seems to just be there as a placeholder.
• Only the parent command should be in the list of commands to be registered, but the parent command function itself is not registered.
• The subcommand function must also be annotated with slash_command.

Assuming these are accurate (which it's entirely possible that they're not), having these things shown in documentation, or even an example, would be great.

Or, is there a more idiomatic way to do this? Documenting that would also be really nice to have.

Here's my code that seems to work as expected:

#[poise::command(
    slash_command,
    subcommands("create"),
)]
async fn class(
    context: Context<'_>,
) -> Result<(), Error> {
    println!("parent command");
    Ok(())
}

#[poise::command(slash_command)]
async fn create(
    context: Context<'_>,
    text: String,
) -> Result<(), Error> {
    println!("test");
    Ok(())
}

Edit: I just found examples/framework_usage/commands/subcommand.rs. Still, a link to this example on the command macro doc page would be greatly appreciated, as well as links to the other similar examples by their relevant documentation. (You always seem to figure stuff out right after you ask for help, don't you?)

[kangalio]

https://kangalioo.github.io/poise/develop/poise/index.html#subcommands