Section headings don't match contents

[stevenengler]

Please complete the following tasks

• I have searched the discussions
• I have searched the existing issues

Rust Version

rustc 1.55.0 (c8dfcfe04 2021-09-06)

Clap Version

master

Minimal reproducible code

use clap::Clap;

#[derive(Debug, Clone, Clap)]
struct CliOptions {
    #[clap(flatten)]
    options_a: OptionsA,

    #[clap(flatten)]
    options_b: OptionsB,
}

#[derive(Debug, Clone, Clap)]
#[clap(help_heading = "HEADING A")]
struct OptionsA {
    #[clap(long)]
    should_be_in_section_a: Option<u32>,
}

#[derive(Debug, Clone, Clap)]
#[clap(help_heading = "HEADING B")]
struct OptionsB {
    #[clap(long)]
    should_be_in_section_b: Option<u32>,
}

fn main() {
    CliOptions::parse();
}

Steps to reproduce the bug with the above code

cargo run -- --help

Actual Behaviour

clap-failure-example

USAGE:
    clap-failure-example [OPTIONS]

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

OPTIONS:
        --should-be-in-section-a <SHOULD_BE_IN_SECTION_A>

HEADING A:
        --should-be-in-section-b <SHOULD_BE_IN_SECTION_B>

Expected Behaviour

clap-failure-example

USAGE:
    clap-failure-example

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

HEADING A:
        --should-be-in-section-a <SHOULD_BE_IN_SECTION_A>

HEADING B:
        --should-be-in-section-b <SHOULD_BE_IN_SECTION_B>

Additional Context

This was broken by #2531.

Debug Output

No response

[pksunkara]

Thanks for digging into this more than needed. Always appreciate the extra info.

[epage]

This was broken by #2531.

App::help_heading is required to be called before adding args but in #2531, we switched to calling app methods after args.

[epage]

My proposal is still the same, we revert #2531 and instead move setting of help/about to into_app. Args should not be setting these while Claps should.

[epage]

@pksunkara I wouldn't classify this as easy until we have a decision made on what we want the behavior to be because help_heading is at tension with the doc comment.

[epage]

Note: this can be worked around by setting the help heading on each arg. Not ideal but one way to be unblocked.

[pksunkara]

I think just the first arg in each flattened struct should be enough as a workaround IIRC.

#[derive(Debug, Clone, Clap)]
struct OptionsA {
    #[clap(long)]
    #[clap(help_heading = "HEADING A")]
    should_be_in_section_a: Option<u32>,
}

[pksunkara]

I will leave the decision of 3.0 milestone to you. I am not sure if what you are proposing needs breaking changes or not.

[stevenengler]

Thanks for the quick replies!

I think just the first arg in each flattened struct should be enough as a workaround IIRC.

It looks like it needs to be set on each individually:

use clap::Clap;

#[derive(Debug, Clone, Clap)]
struct CliOptions {
    #[clap(flatten)]
    options_a: OptionsA,

    #[clap(flatten)]
    options_b: OptionsB,
}

#[derive(Debug, Clone, Clap)]
struct OptionsA {
    #[clap(long)]
    #[clap(help_heading = Some("HEADING A"))]
    should_be_in_section_a: Option<u32>,

    #[clap(long)]
    should_also_be_in_section_a: Option<u32>,
}

#[derive(Debug, Clone, Clap)]
struct OptionsB {
    #[clap(long)]
    #[clap(help_heading = Some("HEADING B"))]
    should_be_in_section_b: Option<u32>,

    #[clap(long)]
    should_also_be_in_section_b: Option<u32>,
}

fn main() {
    CliOptions::parse();
}

clap-failure-example

USAGE:
    clap-failure-example [OPTIONS]

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

OPTIONS:
        --should-also-be-in-section-a <SHOULD_ALSO_BE_IN_SECTION_A>
        --should-also-be-in-section-b <SHOULD_ALSO_BE_IN_SECTION_B>

HEADING A:
        --should-be-in-section-a <SHOULD_BE_IN_SECTION_A>

HEADING B:
        --should-be-in-section-b <SHOULD_BE_IN_SECTION_B>

[epage]

I will leave the decision of 3.0 milestone to you. I am not sure if what you are proposing needs breaking changes or not.

My proposed change would not be an API breakage but a behavior breakage (expectations for what deriving Args does)

[epage]

It looks like it needs to be set on each:

Thanks for confirming this. I was making my assumption based on doc string

Set a custom heading for this arg to be printed under

https://docs.rs/clap/3.0.0-beta.4/clap/struct.Arg.html#method.help_heading

[pksunkara]

Ah, I was confusing that with https://docs.rs/clap/3.0.0-beta.4/clap/struct.App.html#method.help_heading