Improve `--dummy-variables-rgx` and `--ignored-argument-names` documentation

[nortti]

Question

Could the documentation be made more helpful for people trying to ignore dummy arguments?

Documentation for future user

Suppose that I'm looking to suppress unused-argument for all function arguments starting with "mock_".

I might find the option --dummy-variables-rgx:

A regular expression matching the name of dummy variables (i.e. expected to not be used). (default: _+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_)

But wait, it doesn't work. Even though arguments are variables.

I might then find the option --ignored-argument-names:

Argument names that match this expression will be ignored. (default: re.compile('_.*|^ignored_|^unused_'))

The default value looks promising. But wait, why isn't it named --dummy-arguments-rgx? And why is the documentation so different? Is it because this is actually going to suppress a bunch of messages other than unused-variable, such as invalid_name? What does it actually do? Even regular maintainers are confused.

Eventually I learn that it will (at least) suppress unused-variable, too-many-args, and some docstring message(s).

My suggestion is to

• clarify that --dummy-variables-rgx will not work for dummy arguments and point the user towards --ignored-argument-names, and
• make the documentation of --ignored-argument-names clear about what it actually does (what messages it might suppress).

Additional context

No response

[Pierre-Sassoulas]

Thank you for opening the issue. There's three aspect to this:

• Better documentation
• Redesigning both options to have a single option that is used everywhere and that make sense (or have both option but make them mutually exclusive)
• Eating our own dog food (this is [style] Use default 'dummy-variable-rgx' and 'ignored-argument-names' #8014)

[treyra]

Wanted to bump this as another user that expected dummy-variables-rgx to affect arguments, and was surprised and confused when it didn't.

The current FAQ also suggests that they should (see here) so I think it would be most straight forward to have arguments matching dummy-variables-rgx excluded from unused-argument, if that wouldn't break other checks. It's worth noting prefixing the methods name as also suggested in the FAQ works, but I think there are use cases beyond call backs where this feature would be useful, and where blanket suppressing other argument warnings by adding "dummy" to --ignored-argument-names might ignore more than desired.