Top level parser `group_help` breaks help message

[ysndr]

When adding ~documentation~ group_help to the top level parser via a doc comment or thegroup_help` annotation, the generated help message becomes malformatted. It appears as if the doc comments for fields of the parser are interpreted as general documentation:

/// commented command              << this line breaks things
#[derive(Bpaf)]
struct MyArgs {
    /// commended flag
    flag: bool,
}

fn main() {
    my_args().to_options().run();
}

without the parser comment:

Usage: flox [--flag]

Available options:
        --flag  commended flag
    -h, --help  Prints help information

with the parser comment:

Usage: prog [--flag]

commented command
        --flag  commended flag

Available options:
    -h, --help  Prints help information

with group_help

Usage: flox [--flag]

my_args help
        --flag  commended flag

Available options:
    -h, --help  Prints help information

[pacak]

This is somewhat expected behavior. group_help adds a common header for several options. For example in cargo-show-asm I split options into several structs - to make it easier to use internally, this also groups them in --help output:

What kind of use case for group_help do you have in mind?

[ysndr]

Let me try to elaborate, I think this is somewhat related to https://github.com/pacak/bpaf/issues/290 as well

What I'm trying to do is to separate the rust doc comments from cli help. IMO the doc comments are not helpful within rustdoc but i can't add rust doc comments.

thus, in the top-level parser i include groups and set group help either through rustdoc comment (or group_help if i dont particularly care about the rustdoc). I'd like to do so on the group enum itself but group_help in that position seems to be ignored (#290)

However, this way there seems now no way to add a general description to the application as in adding headers and footers to the command. When I add a doc comment or grouphelp to MyArgs here, the groups defined therein are getting messed up.

use bpaf::{Bpaf, Parser};

// /// commented command              << this line breaks things
#[derive(Bpaf)]
// #[bpaf(group_help("breaks stuff too"))]
struct MyArgs {
    /// commended flag
    flag: bool,

    /// primary group description (ignored)
    /// rustdoc comment
    #[bpaf(external(my_group))]
    primary_group: MyGroup,

    /// rustdoc comment
    #[bpaf(external(my_group2), group_help("secondary group description"))]
    secondary: MyGroup2,
}

/// Group of primary subcommands
#[derive(Bpaf, Clone)]
#[bpaf(group_help("primary group description"))] // ignored?
enum MyGroup {
    /// run command
    #[bpaf(command)]
    Run,
}

/// Group of primary subcommands
#[derive(Bpaf, Clone)]
enum MyGroup2 {
    /// build command
    #[bpaf(command)]
    // #[bpaf(help("description for command"))] // unavailable?
    Build,
}

fn main() {
    my_args().to_options().run();
}

[pacak]

I see. I think I understand what you mean, will try to make something to address this issues.

On Mon, Nov 27, 2023, 10:52 Yannik Sander @.***> wrote:

Let me try to elaborate, I think this is somewhat related to #290 https://github.com/pacak/bpaf/issues/290 as well

What I'm trying to do is to separate the rust doc comments from cli help. IMO the doc comments are not helpful within rustdoc but i can't add rust doc comments.

thus, in the top-level parser i include groups and set group help either through rustdoc comment (or group_help if i dont particularly care about the rustdoc). I'd like to do so on the group enum itself but group_help in that position seems to be ignored (#290 https://github.com/pacak/bpaf/issues/290)

However, this way there seems now no way to add a general description to the application as in adding headers and footers to the command. When I add a doc comment or grouphelp to MyArgs here, the groups defined therein are getting messed up.

``rust use bpaf::{Bpaf, Parser};

// /// commented command << this line breaks things

[derive(Bpaf)]

// #[bpaf(group_help("breaks stuff too"))] struct MyArgs { /// commended flag flag: bool,

/// primary group description (ignored) /// rustdoc comment

[bpaf(external(my_group))]

primary_group: MyGroup,

/// rustdoc comment

[bpaf(external(my_group2), group_help("secondary group description"))]

secondary: MyGroup2,

}

/// Group of primary subcommands

[derive(Bpaf, Clone)]

[bpaf(group_help("primary group description"))] // ignored?

enum MyGroup { /// run command

[bpaf(command)]

Run, }

/// Group of primary subcommands

[derive(Bpaf, Clone)]

enum MyGroup2 { /// build command

[bpaf(command)]

// #[bpaf(help("description for command"))] // unavailable? Build, }

fn main() { my_args().to_options().run(); }

— Reply to this email directly, view it on GitHub https://github.com/pacak/bpaf/issues/319#issuecomment-1828109565, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAQFI4TSIV5BHS73T5QAVLYGSZNRAVCNFSM6AAAAAA7V4Z7YKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQMRYGEYDSNJWGU . You are receiving this because you commented.Message ID: @.***>

[ysndr]

Note it behaves differently if using #[bpaf(options)] on the top-level struct, more correctly🤔

[pacak]

I added #[bpaf(ignore_rustdoc)] that you should be able to use at any place that accepts rustdoc comments, unreleased yet. Can you check if it solves your problem?

https://github.com/pacak/bpaf/pull/321

[pacak]

resolved in #321