Option descriptions only make sense "in hindsight"

[ssokolow]

To be perfectly frank, I only know what "More output per occurrence" and "Less output per occurrence" mean because I already know what the options they describe do and how they react to being used more than once.

"per occurrence" is such an opaque choice of phrasing that I'm not even sure they effectively communicate that the somewhat self-documenting --verbose --verbose will do something different from --verbose.

May I suggest taking inspiration from this excerpt from the UltiSnips snippet I use for starting Python scripts?

    parser.add_argument('-v', '--verbose', action="count",
        default=2, help="Increase the verbosity. Use twice for extra effect.")
    parser.add_argument('-q', '--quiet', action="count",
        default=0, help="Decrease the verbosity. Use twice for extra effect.")

That's not ideal and, to be honest, I think I let a little "Avoid having to wrap it onto the next line of the source code" contaminate it, but it's still much more helpful.

Maybe something like "Make console output more verbose. Can be repeated for greater effect."

[epage]

btw this is something you can customize by providing a custom LogLevel.

[ssokolow]

Then that's another documentation bug. I looked through the docs to see if I could figure out how to customize it and, starting from the entry point to the rustdocs, I completely missed that.

...which makes sense. Intuitively, that's sort of like looking on the Iterator trait for a means to customize the Serde derive behaviour of Vec. Conceptually, a logging level is a filter, while the --help output is a property of the filtering framework.

(Granted, it was pretty late at the time, so I did see "Or implement LogLevel yourself for more control." but I more or less thought "No, that's not what I'm looking for. I don't need a custom filter. I need custom documentation." without looking inside.)

Either way, I still think this should be fixed for the default behaviour. I have no problem with copy-pasting one of the stock LogLevel implementations and editing its documentation to give the "Restore Clap 3.x color scheme to the best of my ability" code in my standard project template a friend, but the current state of things makes it more difficult for me to recommend clap-verbosity-flag to others.

[epage]

Then that's another documentation bug.
Either way, I still think this should be fixed for the default behaviour.

To leave room for further exploring this is why I didn't close it when pointing out LogLevel.

#78 improved the docs.

#79 made some tweaks to the help output, taking us from

$ cargo run --example log -Fclap/help -- --help
   Compiling clap v4.0.0
   Compiling clap-verbosity-flag v2.1.0 (/home/epage/src/personal/clap-verbosity-flag)
    Finished dev [unoptimized + debuginfo] target(s) in 2.05s
     Running `target/debug/examples/log --help`
Foo

Usage:

Options:
  -v, --verbose...  More output per occurrence
  -q, --quiet...    Less output per occurrence
  -h, --help        Print help information

to

$ cargo run --example log -- --help
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/examples/log --help`
Foo

Usage: log [OPTIONS]

Options:
  -v, --verbose...  Increase logging verbosity
  -q, --quiet...    Decrease logging verbosity
  -h, --help        Print help information

I didn't both with any commentary on repeated use because clap's ... was added since the text was selected and is meant to convey that.

[ssokolow]

#78 improved the docs.

In case the close/comment race dropped it on the floor, I noticed a typo in the change you were about to merge. ("out" where it should be "the".)

I didn't both with any commentary on repeated use because clap's ... was added since the text was selected and is meant to convey that.

That's fair, but the ... is not a de facto standard part of this sort of documentation, so I'd still include commentary on it to provide an organic way for users to learn that ... in that position means "can be repeated" and not some other behaviour I've seen over the years like Vim-ish "You can type any truncation of --verbose as long as it's still unambiguous".

[epage]

In case the close/comment race dropped it on the floor, I noticed a typo in the change you were about to merge. ("out" where it should be "the".)

It was meant to be "our" and fixed in master

That's fair, but the ... is not a de facto standard part of this sort of documentation

I decided to rely on that because there wasn't a wording I liked and I didn't want progress blocked on perfection.

[ssokolow]

It was meant to be "our" and fixed in master

I suspected as such, but I didn't mention it because, as an anglophone Canadian, it felt more like a weird ESL-ism than something a native speaker would ever choose.

(You're neither in the hospitality industry nor a writer of ad copy and those are the two places I'd expect to see "our" used in that context. Since there's no competition over whose trait is the better solution for the problem of customizing clap-verbosity-flag's output, "our" just feels weird. The compiler only allows one trait to serve that role, so use the definite article.)

[epage]

I suspected as such, but I didn't mention it because, as an anglophone Canadian, it felt more like a weird ESL-ism than something a native speaker would ever choose.

Native speaker :)

I chose "our" to emphasize it is coming from this package

[ssokolow]

Again, I suspected as much from your name, but my point is that putting that emphasis there makes no sense when there's no choice to be made between "our" and "someone else's", so it devolves into feeling like a stylistic choice borrowed from ad copy for the sake of being a stylistic choice borrowed from ad copy.

(Maybe it's just the amount of time I've poured into learning to write fiction, where it's very important to pay close attention to stylistic details like this.)

[epage]

It came from a misunderstanding of your confusion over why you ignored LogLevel. When you were thinking of filtering, I thought you were referring to log::Level and wanted to emphasize the difference.

[ssokolow]

Ahh. That makes sense... but "our" wouldn't have helped in that case. It's too easy to gloss over and interpret as just a stylistic thing.

If you're trying to address that potential mistake, you'd probably want to explicitly say clap_verbosity_flag::LogLevel instead of LogLevel... though I think just ensuring it's a hyperlink and described as serving the desired purpose so people choose to click said link will do fine.