Update user docs to clarify the use of underscores in command method names

[TheFriendlyCoder]

I recently read through a few "defects" in your issue tracker here with complaints about a change in behavior where Click v7 slightly modified the command name mapping logic so that Python method names with underscores in them are renamed to use dashes in their respective command names (ie: def my_command -> tool my-command).

Regardless of the debate that seems to be lively and ongoing on which is better and such, I couldn't help but notice that the description used in the documentation for Click is misleading in this regard. Take this snippet from the latest online docs:

The name of the command defaults to the name of the function.

As I have just illustrated, this is not entirely accurate. When your function name has underscores in it, the command name does not default to the same name as the function. Rather it defaults to the same name as the function but with underscores replaced with dashes.

Given the fact that this behavior is non-obvious to new users such as myself, and confusing when encountered by experienced users who are used to the previous behavior, I'd suggest that updating the docs to reflect this discrepancy would be helpful.

[TheFriendlyCoder]

This request relates to the lengthy discussion thread found here

[TheFriendlyCoder]

Another suggestion: comming into this conversation as a new Click user where I am updating several projects that had used argparse previously, I am focused on preserving compatibility with pre-existing behavior found in argparse whenever possible. For better or worse, many of my custom argparse command groups are named using embedded underscores. Thus this auto-translation of underscores to dashes presented a unique problem for me because I wasn't clear how / why that conversion was happening and what to do about it.

If you do decide to update your API docs, I would suggest adding a brief comment that explains how one goes about "circumventing" this default behavior when necessary. For example, it would have saved me a good 30+ minutes of googling and reading the forums and such if your documentation had said something like: "The name of the decorated function is used as the name of the command, with underscores replaced with dashes. If you need to have a command that has underscores in the name you will have to provide the command name explicitly to the optional 'name' parameter."

[davidism]

Thanks for your comments. Duplicate of #1123. When we address that, the documentation will be part of it.