Help rendering documentation

[grinapo]

I have realised that help rendering using derive mode is… not user friendly.
I wanted to have a short description of the code at the top of help, it didn't work well.

1. It is not described the manual / tutorial
2. It seems to work this way:

• Doc comment before Arg struct become the top text. It goes on until an empty line, all lines appended ("flow text").
• It is not possible to enter neither line break nor an empty line. (Also no colored/bold word, but that's okay.)
• Empty line causes text not to be visible, unless someone asks for --help --help, but it is not told to the user
• When double help is given the lines after the empty line gets printed; but empty lines may or may not render actual empty lines.
• When there are double empty lines, another magic happens: the next line goes after the Usage section.
• ...until the next double empty line, which makes it appear at the end.
• I didn't dare to try more empty lines.

What I wanted was like:

 This foo program does this.
 Sometimes also that.

 Example: ./foo big small little          Does foo on them
          ./foo --reverse small little    Does the opposite
          ./foo --bar                     Bars instead

 Usage:  foo [--bar] [--reverse] THINGS
…

[pacak]

Something like that might do the trick:

/// This foo program does this.
///  Sometimes also that.
#[derive(Debug, Clone, Bpaf)]
#[bpaf(options)]
struct Options {
...

Each section is transformed according to those rules: https://docs.rs/bpaf/0.9.23/bpaf/params/struct.NamedArg.html#method.help

[pacak]

To insert a blank line you need to add a line that contains a single space. Might be tricky if your editor is set to trim them, but you can use #[doc = " "].

So I typed this to one of the examples

/// This foo program does this.
///  Sometimes also that.
#[doc = "  "]
///  Example: ./foo big small little          Does foo on them
///              ./foo --reverse small little    Does the opposite
///              ./foo --bar                     Bars instead
struct Opts {

And got this as output:

This foo program does this.
Sometimes also that.

Example: ./foo big small little          Does foo on them
         ./foo --reverse small little    Does the opposite
         ./foo --bar                     Bars instead

Usage: derive [-d] [-v]... [--speed=SPEED] --output=ARG [--nb-cars=ARG] [--files-to-process=ARG]...

[grinapo]

https://docs.rs/bpaf/latest/bpaf/_documentation/_1_tutorials/ may love such informations! 😄

(More specifically https://docs.rs/bpaf/latest/bpaf/_documentation/_1_tutorials/_2_derive_api/_9_help/ )

[pacak]

Totally agree :) I'm working on a bigger refactor right now and will be rewriting the tutorials as well.

[grinapo]

Hmm, also your example doesn't work, I need:

///  Sometimes also that.
#[doc = "  "]
#[doc = " "]
///  Example: ./foo big small little          Does foo on them

to get the result.

Correction: it works if I enter the extra space at the beginning. It is hard to see on this github rendering. :-)

[grinapo]

And shouldn't available options list --help --help as well, if there is more help to meet the eye?