Add .suppressWarnings() for warnings in #1915 #1931 #1938 #1940

[aweebit]

Peer PRs

Requires changes when merged with…

• Add async custom processing support. Add chainArgParserCalls() for configuration. Additionally await thenable implicit and default option values and thenable default argument values #1915
• Warn about obscured help option #1931
• Add support for sharing and stand-alone parsing of subcommands. Warn about parse calls on commands added with .command() #1938
• Warn about async calls in .parse() #1940

👉 ❗ 💬 This PR is the place for discussions about the warning model that apply to all of the PRs listed above!

Incompatible with…

• React to wrong library usage #1917: parse methods shall never be called on subcommands, so if warnings about such calls are added, the JSDoc and the ChangeLog entry for .suppressWarnings() introduced here become incorrect. The fact there is currently no well-defined meaning for such calls is one of the reasons why #1938 and #1940 should be preferred over #1917!

Changes summary

Proposed mistake handling model

Based on #1940 (comment). Could be added to the docs.

• suspicious library usage patterns (although not always entirely wrong): assume author mistake and show a warning unless suppressWarnings is on – a setting added specifically so that warnings can be hidden from end users
• end user mistakes, including arguments deemed invalid by argParsers: display an error message and exit the program (by default)
• other errors originating in callbacks (argParsers, hooks, actions): throw the error for the author to handle – should not be seen by end user

ChangeLog

Added

• .suppressWarnings() to suppress warnings about presumably wrong library usage

Some explanations

Why .suppressWarning() instead of an environment variable such as NODE_ENV (as originally proposed)?

Environment variables are used for stuff the end user should be able to control, but in our case, the tool author is the one to decide whether the warnings are to be shown.

See also: #1940 (comment).

[shadowspawn]

Lots of mind-dump comments.

Warnings are something I think about in general, and applicable to multiple of your suggested PRs. Not ready for a big control switch yet.

A somewhat related concept is "convention over configuration": https://en.wikipedia.org/wiki/Convention_over_configuration

I think suppressing the warnings would need a narrower more explicit focus than just "warnings".

In general I prefer messages to be for high-value issues that don't need to be made conditional.

On a vaguely related note, I have thought about added in combined make-old-programs-work configuration, but got talked out of it the one time I wrote code. And I think it doesn't work as a concept in the longterm. Instead, I have been explicit about documenting deprecated patterns, but not removing them until there is a gain for the client pain.

There is potentially a tension between the mistakes someone makes when very first attempting to use the library, versus the things authors try adding isolated custom behaviour or making major additions.