Option naming: add test and documentation for existing functionality

docs/options.rst

@@ -16,8 +16,9 @@ Basic Value Options
 The most basic option is a value option.  These options accept one
 argument which is a value.  If no type is provided, the type of the default
 value is used.  If no default value is provided, the type is assumed to be
-:data:`STRING`.  By default, the name of the parameter is the first long
-option defined; otherwise the first short one is used.
+:data:`STRING`.  Unless a name is explicitly specified, the name of the
+parameter is the first long option defined; otherwise the first short one is
+used.
 
 .. click:example::
 
@@ -26,6 +27,15 @@ option defined; otherwise the first short one is used.
     def dots(n):
         click.echo('.' * n)
 
+.. click:example::
+
+    # How to use a Python reserved word such as `from` as a parameter
+    @click.command()
+    @click.option('--from', '-f', '_from')
+    @click.option('--to', '-t')
+    def reserved_param_name(_from, to):
+        click.echo('from %s to %s' % (_from, to))
+
 And on the command line:
 
 .. click:run::

tests/test_options.py

@@ -345,8 +345,11 @@ def cli_alt(warnings):
     (['-c', '-b', '-a'], 'c'),
     (['-a', '--apple', '-b', '--banana', '-c', '--cantaloupe'], 'apple'),
     (['-c', '-a', '--cantaloupe', '-b', '--banana', '--apple'], 'cantaloupe'),
+    (['--from', '-f', '_from'], '_from'),
+    (['--return', '-r', '_ret'], '_ret'),
 ])
-def test_multiple_long_options(runner, option_args, expected):
+def test_option_names(runner, option_args, expected):
+
     @click.command()
     @click.option(*option_args, is_flag=True)
     def cmd(**kwargs):
@@ -355,5 +358,6 @@ def cmd(**kwargs):
     assert cmd.params[0].name == expected
 
     for form in option_args:
-        result = runner.invoke(cmd, [form])
-        assert result.output == 'True\n'
+        if form.startswith('-'):
+            result = runner.invoke(cmd, [form])
+            assert result.output == 'True\n'