Add docs for AutocompleteContext, Option, OptionChoice, and on_application_command* events. (#1103)

* add docs for `AutocompleteContext`, `Option`, `OptionChoice`, and  `on_application_command*` events.

* revert unnecessary additional typing

* add versionadded to more docstrings

Author: krittick

discord/commands/context.py

@@ -290,7 +290,7 @@ class AutocompleteContext:
         The option the user is currently typing.
     value: :class:`.str`
         The content of the focused option.
-    options :class:`.dict`
+    options: :class:`.dict`
         A name to value mapping of the options that the user has selected before this option.
     """
 

discord/commands/options.py

@@ -57,6 +57,58 @@ def __name__(self):
 
 
 class Option:
+    """Represents a selectable option for a slash command.
+
+    Examples
+    --------
+    Basic usage: ::
+
+        @bot.slash_command(guild_ids=[...])
+        async def hello(
+            ctx: discord.ApplicationContext,
+            name: Option(str, "Enter your name"),
+            age: Option(int, "Enter your age", min_value=1, max_value=99, default=18)
+            # passing the default value makes an argument optional
+            # you also can create optional argument using:
+            # age: Option(int, "Enter your age") = 18
+        ):
+            await ctx.respond(f"Hello! Your name is {name} and you are {age} years old.")
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ----------
+    input_type: :class:`Any`
+        The type of input that is expected for this option.
+    description: :class:`str`
+        The description of this option.
+        Must be 100 characters or fewer.
+    name: :class:`str`
+        The name of this option visible in the UI.
+        Inherits from the variable name if not provided as a parameter.
+    choices: Optional[List[Union[:class:`Any`, :class:`OptionChoice`]]]
+        The list of available choices for this option.
+        Can be a list of values or :class:`OptionChoice` objects (which represent a name:value pair).
+        If provided, the input from the user must match one of the choices in the list.
+    required: Optional[:class:`bool`]
+        Whether this option is required.
+    default: Optional[:class:`Any`]
+        The default value for this option. If provided, ``required`` will be considered ``False``.
+    min_value: Optional[:class:`int`]
+        The minimum value that can be entered.
+        Only applies to Options with an input_type of ``int`` or ``float``.
+    max_value: Optional[:class:`int`]
+        The maximum value that can be entered.
+        Only applies to Options with an input_type of ``int`` or ``float``.
+    autocomplete: Optional[:class:`Any`]
+        The autocomplete handler for the option. Accepts an iterable of :class:`str`, a callable (sync or async) that takes a
+        single argument of :class:`AutocompleteContext`, or a coroutine. Must resolve to an iterable of :class:`str`.
+
+        .. note::
+
+            Does not validate the input value against the autocomplete results.
+    """
+
     def __init__(self, input_type: Any, /, description: str = None, **kwargs) -> None:
         self.name: Optional[str] = kwargs.pop("name", None)
         self.description = description or "No description provided"
@@ -139,6 +191,19 @@ def __repr__(self):
 
 
 class OptionChoice:
+    """
+    Represents a name:value pairing for a selected :class:`Option`.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ----------
+    name: :class:`str`
+        The name of the choice. Shown in the UI when selecting an option.
+    value: Optional[Union[:class:`str`, :class:`int`, :class:`float`]]
+        The value of the choice. If not provided, will use the value of ``name``.
+    """
+
     def __init__(self, name: str, value: Optional[Union[str, int, float]] = None):
         self.name = name
         self.value = value if value is not None else name

discord/ui/input_text.py

@@ -16,6 +16,8 @@
 class InputText:
     """Represents a UI text input field.
 
+    .. versionadded:: 2.0
+
     Parameters
     ----------
     style: :class:`discord.InputTextStyle`

discord/ui/modal.py

@@ -24,6 +24,8 @@ class Modal:
 
     This object must be inherited to create a UI within Discord.
 
+    .. versionadded:: 2.0
+
     Parameters
     ----------
     title: :class:`str`

docs/api.rst

@@ -160,6 +160,14 @@ ApplicationContext
 .. autoclass:: ApplicationContext
     :members:
 
+AutocompleteContext
+~~~~~~~~~~~~~~~~~~~
+
+.. attributetable:: AutocompleteContext
+
+.. autoclass:: AutocompleteContext
+    :members:
+
 Application Info
 ------------------
 
@@ -745,6 +753,36 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     :param interaction: The interaction data.
     :type interaction: :class:`Interaction`
 
+.. function:: on_application_command(context)
+
+    Called when an application command is received.
+
+    .. versionadded:: 2.0
+
+    :param context: The ApplicationContext associated to the command being received.
+    :type context: :class:`ApplicationContext`
+
+.. function:: on_application_command_completion(context)
+
+    Called when an application command is completed, after any checks have finished.
+
+    .. versionadded:: 2.0
+
+    :param context: The ApplicationContext associated to the command that was completed.
+    :type context: :class:`ApplicationContext`
+
+.. function:: on_application_command_error(context, exception)
+
+    Called when an application command has an error.
+
+    .. versionadded:: 2.0
+
+    :param context: The ApplicationContext associated to the command that has an error.
+    :type context: :class:`ApplicationContext`
+
+    :param exception: The DiscordException associated to the error.
+    :type exception: :class:`DiscordException`
+
 .. function:: on_private_channel_update(before, after)
 
     Called whenever a private group DM is updated. e.g. changed name or topic.
@@ -1335,6 +1373,8 @@ Utility Functions
 
 .. autofunction:: discord.utils.generate_snowflake
 
+.. autofunction:: discord.utils.basic_autocomplete
+
 .. _discord-api-enums:
 
 Enumerations