Should Document extend Command?

[boblail]

The root CLI is a command.

Note

Most CLI frameworks model it this way:

• alecthomas/kong (Go): the root CLI and commands are all modeled as Go structs using Kong's grammar
• oclif/oclif (TS): the root CLI and commands are all modeled as classes that extend Command
• spf13/cobra (Go): the root command and subcommands are all instances of *cobra.Command
• clap-rs/clap (Rust): the root and subcommands are all clap::Command values composed into a tree
• remkop/picocli (Java): the root command and subcommands are all @Command-annotated classes/objects
• commander-js/commander.js (JS): the “program” and its subcommands are all Command objects
• CLIUtils/CLI11 (C++): the root app and subcommands are all CLI::App objects (subcommands are Apps too!)

There are exceptions —

• urfave/cli (Go): the root is a cli.App that contains []cli.Command
• dotnet/command-line-api (C#): the root is a RootCommand rather than just Command
• pallets/click (Python): the root is typically a click.Group rather than a plain click.Command

— but even among these, it's typical for the root command to extend the branch command (System.CommandLine.RootCommand extends System.CommandLine.Command and click.Group extends click.Command)

Both Document and Command have fields for arguments, options, commands, examples, etc. However Document puts its name and description under info.

CliInfo subtly diverges from Command:

• Why does CliInfo have a title but Command has a name?
  • Can we settle on name?
• Why does CliInfo have a summary and a description but Command only has a description?
  • How do summary and description differ?
  • Is Command's description intended to be the one-line string displayed in a menu of commands?

Command's hidden flag is perhaps meaningless for the root command, but other than that, I think the spec would be strengthened by modeling Document as a superset of Command.

[boblail]

Here's how this change might look: #74