Repository: pallets/click

Issue:
Documentation of decorators should should show where to look for arguments' reference  
I've just started exploring click, and wholeheartedly love it. Thanks!

One thing that made the experience a bit frustrating was the API reference. Currently, in some places, it omits descriptions of the arguments of some of the decorators. For example, with [`click.argument`](https://click.palletsprojects.com/en/8.1.x/api/#click.argument), it just says the type is `Any` without telling where to look for the actual description:

![image](https://user-images.githubusercontent.com/6691643/167310684-18074b81-3932-4bc8-b7e4-5af48cf8f8b2.png)

I guess it's because the underlying argument class is customizable, but for the default usecase it would be nice to have a reference to the default.

Clicking on the reference to [`click.Argument`](https://click.palletsprojects.com/en/8.1.x/api/#click.Argument) doesn't reveal much either:

![image](https://user-images.githubusercontent.com/6691643/167310805-d624ec5c-728a-4f73-9f72-43c7a86ee9c9.png)

It would be nice if the description of `attrs` pointed to their actual reference: [`click.Parameter`](https://click.palletsprojects.com/en/8.1.x/api/#click.Parameter) in case of `argument` and `option` decorators.

There's already a precedent for this in the docs - [`click.Group`](https://click.palletsprojects.com/en/8.1.x/api/#click.Group):
![image](https://user-images.githubusercontent.com/6691643/167312103-295a3eee-42c7-436a-a2e0-cbbaebb001b0.png)



Discussion:

Resolving patch:
diff --git a/src/click/core.py b/src/click/core.py
--- a/src/click/core.py
+++ b/src/click/core.py
@@ -1480,6 +1480,7 @@ class MultiCommand(Command):
     :param result_callback: The result callback to attach to this multi
         command. This can be set or changed later with the
         :meth:`result_callback` decorator.
+    :param attrs: Other command arguments described in :class:`Command`.
     """
 
     allow_extra_args = True
@@ -1944,6 +1945,9 @@ class CommandCollection(MultiCommand):
     commands together into one.  This is a straightforward implementation
     that accepts a list of different multi commands as sources and
     provides all the commands for each of them.
+
+    See :class:`MultiCommand` and :class:`Command` for the description of
+    ``name`` and ``attrs``.
     """
 
     def __init__(
@@ -2467,6 +2471,7 @@ class Option(Parameter):
                                context.
     :param help: the help string.
     :param hidden: hide this option from help outputs.
+    :param attrs: Other command arguments described in :class:`Parameter`.
 
     .. versionchanged:: 8.1.0
         Help text indentation is cleaned here instead of only in the
@@ -2945,7 +2950,7 @@ class Argument(Parameter):
     provide fewer features than options but can have infinite ``nargs``
     and are required by default.
 
-    All parameters are passed onwards to the parameter constructor.
+    All parameters are passed onwards to the constructor of :class:`Parameter`.
     """
 
     param_type_name = "argument"
diff --git a/src/click/decorators.py b/src/click/decorators.py
--- a/src/click/decorators.py
+++ b/src/click/decorators.py
@@ -336,8 +336,14 @@ def argument(*param_decls: str, **attrs: t.Any) -> _Decorator[FC]:
     This is equivalent to creating an :class:`Argument` instance manually
     and attaching it to the :attr:`Command.params` list.
 
+    For the default argument class, refer to :class:`Argument` and
+    :class:`Parameter` for descriptions of parameters.
+
     :param cls: the argument class to instantiate.  This defaults to
                 :class:`Argument`.
+    :param param_decls: Passed as positional arguments to the constructor of
+        ``cls``.
+    :param attrs: Passed as keyword arguments to the constructor of ``cls``.
     """
 
     def decorator(f: FC) -> FC:
@@ -355,8 +361,14 @@ def option(*param_decls: str, **attrs: t.Any) -> _Decorator[FC]:
     This is equivalent to creating an :class:`Option` instance manually
     and attaching it to the :attr:`Command.params` list.
 
+    For the default option class, refer to :class:`Option` and
+    :class:`Parameter` for descriptions of parameters.
+
     :param cls: the option class to instantiate.  This defaults to
                 :class:`Option`.
+    :param param_decls: Passed as positional arguments to the constructor of
+        ``cls``.
+    :param attrs: Passed as keyword arguments to the constructor of ``cls``.
     """
 
     def decorator(f: FC) -> FC:


Test patch: