#3175

If #3191 is approved I'd be happy to go back and handle any merge conflicts caused by this PR's changes.

Clarity improvements

• The "Option Decorator" section refers to "positional arguments" of the click.option() decorator and to the "function argument" of the decorated callback function. Using "positional arguments" as shorthand for "positional arguments passed to the option() decorator" introduces ambiguity, because the decorated function can also accept positional arguments (and in fact does in every provided example). Using "function" as shorthand for "decorated function" is also ambiguous. References to the positional arguments for click.option() are changed to "parameter declarations" (for consistency with the API docs), and "function argument" is replaced with the more specific "callback argument".

• When describing the steps to infer the callback argument name from the parameter declarations, the following is misleading (possibly outdated?):

  1. If a positional argument name does not have a prefix, it is chosen.

  The actual criteria is that the argument is a valid identifier, i.e. str.isidentifier() returns True (see Option._parse_decls()). A string that is "prefixed" with _ would therefore be chosen. The step is updated to reflect this and links to Python's "Lexical analysis" documentation.

• Several sections use "pass in" back-to-back when referencing option() arguments and command line usage. This makes it unclear when the command line usage is being referenced. When referring to option(), instead use "declare" for positional arguments or "set" for keyword arguments.

Consistency improvements

• All instances of "underlying function" are replaced with "decorated function".

• References to "dash(es)" are replaced with - or --. This establishes consistency with the "Other Prefix Characters" section and allows for several sentences to be reworded for concision.

Miscellaneous

Minor grammar and concision edits throughout.