Argument --verbosity is not intuitive

[loximann]

Description
--verbosity in Catch2 applications has a different behaviour than usually expected.

• --verbose/--verbosity is usually found to increase the output in a normal run for debugging purposes (see eg https://en.wikipedia.org/wiki/Verbose_mode). In Catch2, it is used solely to set the level of detail provided by running with --list-*.
• The verbosity level "quiet" is not very intuitive: one would expect that normal output is suppressed, eg only errors are printed.
• The command line help string "set output verbosity" does not indicate that only --list-* runs are affected, and that normal runs are not.

Preferably the option could be renamed to something like "level of detail" (and "quiet" replaced with "low"), as an alias not to break the interface. At least the help string should be changed to something like "set the level of detail for the --list-* options".

Additional context

--list-test-names-only was removed in #1190

[loximann]

Preliminary addition to documentation:
https://github.com/loximann/Catch2/blob/document_verbosity/docs/command-line.md#listing-available-tests-tags-or-reporters

I could not document --list-listeners because it crashes. I will look into it tomorrow.

[horenmar]

After some investigation, you are right in that verbosity is currently only taken into account by the listings.

However, it is also meant for reporters if they can meaningfully support it. Most of the custom reporters are meant to be machine-friendly, so it is likely meaningless for them, but e.g. the Console reporter could support different verbosities... if someone bothers to add them (I probably won't, as the effort to do so isn't worth it for me).

---

nitpick on the docs: You should mention that this is for the default listing implementation, and I think that the normal (default) verbosity should be the one with docs, and the other ones should be documented as diffs from the normal. (So normal shouldn't be "same as quiet", but quiet should be "same as normal".)

[loximann]

No nitpicking, it is a good suggestion. I have this now:

https://github.com/loximann/Catch2/blob/document_verbosity/docs/command-line.md#listing-available-tests-tags-or-reporters

Do you think I should create a PR and move discussion over there?

[horenmar]

Opening up a new PR would be better, yes.