Derive help from type comment iinstead of struct comment

[aThorp96]

Make sure you completed the following tasks

• Searched the discussions
• Searched the closed issues

Describe your use case

If I have a number of commands that operate similarly, I may structure the command as such:

/// Base action which provides the necessary parameters
#[derive(Clap, Debug, Clone, PartialEq)]
struct BaseAction {
    filename: String,
    // It's fair to assume this is a more complex struct, given its use case
}

/// Does some action
type Action1 = BaseAction;
/// Does some other action
type Action2 = BaseAction;

/// Do an action
#[derive(Clap, Debug, Clone, PartialEq)]
enum Do {
    One(Action1),
    Two(Action2),
}

However when this is done, the help generated uses the comment Base action which provides the necessary parameters for both Action1 and Action2. This makes sense in that you cannot derive on a type, so it clap may not know where to find the comments. However that would be very nice. In order to provide meaningful help to those subcommands I need to use a doc comment on the variants of the command, which is obviously not the best place for them.

Describe the solution you'd like

Ideally using the same code as before, clap's derivation would see that the type of Do::One is not actually BaseAction but Action1, and use its doc comment to derive help. I'm not sure how possible that is with the way clap derives, however.

Alternatives, if applicable

The current alternative is somewhat bad IMO, but does work. That is to comment on the variant itself. This is less than ideal because there is no documentation on the type, or duplication in documentation, which is too easy to get out of sync as it is.

/// Base action which provides the necessary parameters
#[derive(Clap, Debug, Clone, PartialEq)]
struct BaseAction {
    filename: String,
    // It's fair to assume this is a more complex struct, given its use case
}

type Action1 = BaseAction;
type Action2 = BaseAction;

/// Do an action
#[derive(Clap, Debug, Clone, PartialEq)]
enum Do {
    /// Does some action
    One(Action1),
    /// Does some other action
    Two(Action2),
}

[pksunkara]

Ideally using the same code as before, clap's derivation would see that the type of Do::One is not actually BaseAction but Action1, and use its doc comment to derive help. I'm not sure how possible that is with the way clap derives, however.

That's not how rust derive macros work. They can't see outside the scope they are defined for. And type statements don't support derive macros either. Basically, this is impossible as of now.

The alternative is the recommended way to do this. Infact you don't even need to define the types separately here.

/// Do an action
#[derive(Clap, Debug, Clone, PartialEq)]
enum Do {
    /// Does some action
    One(BaseAction),
    /// Does some other action
    Two(BaseAction),
}

[aThorp96]

That makes sense. Thanks @pksunkara