Top level parser group_help breaks help message

[ysndr]

When adding documentation group_help to the top level parser via a doc comment or the group_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 #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 <#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 <#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 <#319 (comment)>, 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?

#321

[pacak]

resolved in #321