Help text not shown when using doc comment on externalized subcommand

[hampuslidin]

I have a structure like this:

#[derive(Debug, StructOpt)]
#[structopt(name = "todo")]
/// A todo tool.
struct Todo {
    #[structopt(subcommand)]
    subcommand: Subcommand,
}

#[derive(Debug, StructOpt)]
enum Subcommand {
    New(New),
}

#[derive(Debug, StructOpt)]
/// Create a new task.
struct New {
    /// The title of the task.
    title: String,
}

Invoking cargo run -- help yields:

todo 0.1.0
A todo tool.

USAGE:
    todo <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help    Prints this message or the help of the given subcommand(s)
    new

It would be great if the doc comment on the externalized subcommand could be used as the help message, instead of having it by the enum cases. The same goes for using the about field in the structopt attribute.

[CreepySkeleton]

Try this

#[derive(Debug, StructOpt)]
enum Subcommand {
    /// Create a new task.
    New(New),
}

#[derive(Debug, StructOpt)]
struct New {
    /// The title of the task.
    title: String,
}

[hampuslidin]

Thanks for your solution! I am leaning towards this approach now as well for other reasons, but there might be situations where it makes more sense to have the description tied to the defining struct, as to make the code documentation more clear. But maybe that is nitpicking ;)

[CreepySkeleton]

@TeXitoi I just realized that flatten doesn't work on enum variants while it should. Am I right? If I am - that's a bug introduced by me in #229, oops.

EDIT: Nope, not by me :)

EDIT2: Not a bug. It looks like...

[TeXitoi]

Can you provide an example and thé behavior you expect?

[hampuslidin]

Sure. As a bare minimum example:

#[derive(Debug, StructOpt)]
#[structopt(name = "todo")]
/// A todo tool.
enum Todo {
    New(New),
}

#[derive(Debug, StructOpt)]
/// Create a new task
struct New {
    /// The title of the task
    title: String,
}

or

#[derive(Debug, StructOpt)]
#[structopt(name = "todo", about = "A todo tool.")]
enum Todo {
    New(New),
}

#[derive(Debug, StructOpt)]
#[structopt(about = "Create a new task")]
struct New {
    #[structopt(about = "The title of the task")]
    title: String,
}

I would expect cargo run -- help to output:

todo 0.1.0
A todo tool.

USAGE:
    todo <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help    Prints this message or the help of the given subcommand(s)
    new     Create a new task

[CreepySkeleton]

We may make this possible by allowing #[flatten] on single-typed enum variants

[CreepySkeleton]

Funny thing - this is exactly how things work now :) see #333

I'm also closing this since implementing this design variant would be breaking change and structopt is unlikely to have another minor release. It is also very unclear what we should do (and what we can do) if both of the comments are present.