`bpaf-derive` no longer uses full doc string for help

[Scott Lamb]

It looks like bpaf-derive behavior changed recently, I'm guessing in 0.5.0. The help output used to be the full doc string. Now, it just seems to be the first line/sentence/whatever. I'm guessing this is an accident? I don't see it in the changelog. From my work-in-progress upgrade:

/// Runs the server, saving recordings and allowing web access.
#[derive(Bpaf, Debug)]
#[bpaf(options)]
pub struct Args {
    /// Path to configuration file.
    ///
    /// default: `/etc/moonfire-nvr.toml`. See `ref/config.md` for config file documentation.
    #[bpaf(short, long, argument("PATH"), fallback_with(config_fallback))]
    config: PathBuf,
    ...

Before:

Runs the server, saving recordings and allowing web access.

Usage: nvr run [-c PATH] [--read-only]

Available options:
    -c, --config <PATH>  Path to configuration file.
                         default: `/etc/moonfire-nvr.toml`. See `ref/config.md` for config file documentation.
        --read-only      Opens the database in read-only mode and disables recording.
                         Note this is incompatible with session authentication; consider adding
                         a bind with `allowUnauthenticatedPermissions` to your config.
    -h, --help           Prints help information

After:

Runs the server, saving recordings and allowing web access.

Usage: moonfire-nvr run [-c=PATH] [--read-only]

Available options:
    -c, --config=PATH  Path to configuration file.
        --read-only    Opens the database in read-only mode and disables recording.
    -h, --help         Prints help information

[pacak]

The original idea was to use blank lines to split help message into partial help and full help and I though it was implemented this way since the beginning but it turns out there was a bug. If you want to include everything - drop the blank line. Alternatively users can pass -- help twice (or -hh) to see the long help message.

A more detailed explanation and some examples are here https://docs.rs/bpaf/latest/bpaf/parsers/struct.NamedArg.html#method.help

[Scott Lamb]

Thanks again! I probably should have seen/remembered that documentation you linked. Still, it'd be good to mention this fix in the changelog, as I'm probably not the only one who expects something like this to be called out there.

[pacak]

Yea, 0.9.1 is coming soon with fixes to most of the issues you found. Appreciate your help.

[Scott Lamb]

btw, is the -hh or --help --help a common convention that I've missed? I don't recall it in other programs, and I don't see any hint of it in the regular --help output, so I don't think my users would ever know to pass it. I will drop the blank line.

[pacak]

I'm pretty sure I saw it somewhere at least.

Main goal for long and short help is to be able to generate detailed documentation in markdown with all the flags documented like I'm doing here with README.md: https://github.com/pacak/cargo-show-asm/tree/bpaf9 - this way CI can check that flag documentation is up to date.

As for having a hint in the regular --help output - you can customize the message used by --help parser as well as the name itself using OptionParser::help_parser.

https://docs.rs/bpaf/latest/bpaf/struct.OptionParser.html#method.help_parser

[pacak]

Updated docs, updated changelog.