From b4b953bfc66adc235e06774b0481ceb847753793 Mon Sep 17 00:00:00 2001 From: Sebastian Law <44045823+SebbyLaw@users.noreply.github.com> Date: Sun, 28 Jun 2020 00:45:58 -0700 Subject: Fix various inconsistencies within the documentation (#5067) --- discord/ext/commands/bot.py | 13 +++++++---- discord/ext/commands/cog.py | 22 ++++++++++++----- discord/ext/commands/context.py | 32 ++++++++++++++----------- discord/ext/commands/core.py | 52 ++++++++++++++++++++++++----------------- discord/ext/commands/errors.py | 2 +- discord/ext/commands/help.py | 2 +- 6 files changed, 76 insertions(+), 47 deletions(-) (limited to 'discord/ext') diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py index 8485c4ab..724ab7cb 100644 --- a/discord/ext/commands/bot.py +++ b/discord/ext/commands/bot.py @@ -215,7 +215,7 @@ class BotBase(GroupMixin): The function that was used as a global check. call_once: :class:`bool` If the function should only be called once per - :meth:`Command.invoke` call. + :meth:`.Command.invoke` call. """ if call_once: @@ -248,7 +248,7 @@ class BotBase(GroupMixin): r"""A decorator that adds a "call once" global check to the bot. Unlike regular global checks, this one is called only once - per :meth:`Command.invoke` call. + per :meth:`.Command.invoke` call. Regular global checks are called whenever a command is called or :meth:`.Command.can_run` is called. This type of check @@ -513,6 +513,11 @@ class BotBase(GroupMixin): The name of the cog you are requesting. This is equivalent to the name passed via keyword argument in class creation or the class name if unspecified. + + Returns + -------- + Optional[:class:`Cog`] + The cog that was requested. If not found, returns ``None``. """ return self.__cogs.get(name) @@ -991,11 +996,11 @@ class Bot(BotBase, discord.Client): :meth:`.is_owner` then it is fetched automatically using :meth:`~.Bot.application_info`. owner_ids: Optional[Collection[:class:`int`]] - The user IDs that owns the bot. This is similar to `owner_id`. + The user IDs that owns the bot. This is similar to :attr:`owner_id`. If this is not set and the application is team based, then it is fetched automatically using :meth:`~.Bot.application_info`. For performance reasons it is recommended to use a :class:`set` - for the collection. You cannot set both `owner_id` and `owner_ids`. + for the collection. You cannot set both ``owner_id`` and ``owner_ids``. .. versionadded:: 1.3 """ diff --git a/discord/ext/commands/cog.py b/discord/ext/commands/cog.py index 5c81e4a5..b8e25917 100644 --- a/discord/ext/commands/cog.py +++ b/discord/ext/commands/cog.py @@ -72,7 +72,7 @@ class CogMeta(type): The cog name. By default, it is the name of the class with no modification. command_attrs: :class:`dict` A list of attributes to apply to every command inside this cog. The dictionary - is passed into the :class:`Command` (or its subclass) options at ``__init__``. + is passed into the :class:`Command` options at ``__init__``. If you specify attributes inside the command attribute in the class, it will override the one specified inside this attribute. For example: @@ -188,12 +188,16 @@ class Cog(metaclass=CogMeta): return self def get_commands(self): - r"""Returns a :class:`list` of :class:`.Command`\s that are - defined inside this cog. + r""" + Returns + -------- + List[:class:`.Command`] + A :class:`list` of :class:`.Command`\s that are + defined inside this cog. - .. note:: + .. note:: - This does not include subcommands. + This does not include subcommands. """ return [c for c in self.__cog_commands__ if c.parent is None] @@ -221,7 +225,13 @@ class Cog(metaclass=CogMeta): yield from command.walk_commands() def get_listeners(self): - """Returns a :class:`list` of (name, function) listener pairs that are defined in this cog.""" + """Returns a :class:`list` of (name, function) listener pairs that are defined in this cog. + + Returns + -------- + List[Tuple[:class:`str`, :ref:`coroutine `]] + The listeners defined in this cog. + """ return [(name, getattr(self, method_name)) for name, method_name in self.__cog_listeners__] @classmethod diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py index 5635cb42..bb48935c 100644 --- a/discord/ext/commands/context.py +++ b/discord/ext/commands/context.py @@ -52,16 +52,14 @@ class Context(discord.abc.Messageable): :func:`on_command_error` event then this dict could be incomplete. prefix: :class:`str` The prefix that was used to invoke the command. - command - The command (i.e. :class:`.Command` or its subclasses) that is being - invoked currently. + command: :class:`Command` + The command that is being invoked currently. invoked_with: :class:`str` The command name that triggered this invocation. Useful for finding out which alias called the command. - invoked_subcommand - The subcommand (i.e. :class:`.Command` or its subclasses) that was - invoked. If no valid subcommand was invoked then this is equal to - ``None``. + invoked_subcommand: :class:`Command` + The subcommand that was invoked. + If no valid subcommand was invoked then this is equal to ``None``. subcommand_passed: Optional[:class:`str`] The string that was attempted to call a subcommand. This does not have to point to a valid registered subcommand and could just point to a @@ -110,7 +108,7 @@ class Context(discord.abc.Messageable): Parameters ----------- command: :class:`.Command` - A command or subclass of a command that is going to be called. + The command that is going to be called. \*args The arguments to to use. \*\*kwargs @@ -188,7 +186,7 @@ class Context(discord.abc.Messageable): @property def valid(self): - """Checks if the invocation context is valid to be invoked with.""" + """:class:`bool`: Checks if the invocation context is valid to be invoked with.""" return self.prefix is not None and self.command is not None async def _get_channel(self): @@ -196,7 +194,7 @@ class Context(discord.abc.Messageable): @property def cog(self): - """Returns the cog associated with this context's command. None if it does not exist.""" + """:class:`.Cog`: Returns the cog associated with this context's command. None if it does not exist.""" if self.command is None: return None @@ -204,22 +202,28 @@ class Context(discord.abc.Messageable): @discord.utils.cached_property def guild(self): - """Returns the guild associated with this context's command. None if not available.""" + """Optional[:class:`.Guild`]: Returns the guild associated with this context's command. None if not available.""" return self.message.guild @discord.utils.cached_property def channel(self): - """Returns the channel associated with this context's command. Shorthand for :attr:`.Message.channel`.""" + """:class:`.TextChannel`: + Returns the channel associated with this context's command. Shorthand for :attr:`.Message.channel`. + """ return self.message.channel @discord.utils.cached_property def author(self): - """Returns the author associated with this context's command. Shorthand for :attr:`.Message.author`""" + """Union[:class:`~discord.User`, :class:`.Member`]: + Returns the author associated with this context's command. Shorthand for :attr:`.Message.author` + """ return self.message.author @discord.utils.cached_property def me(self): - """Similar to :attr:`.Guild.me` except it may return the :class:`.ClientUser` in private message contexts.""" + """Union[:class:`.Member`, :class:`.ClientUser`]: + Similar to :attr:`.Guild.me` except it may return the :class:`.ClientUser` in private message contexts. + """ return self.guild.me if self.guild is not None else self.bot.user @property diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py index 9534f527..7bfe6196 100644 --- a/discord/ext/commands/core.py +++ b/discord/ext/commands/core.py @@ -142,12 +142,11 @@ class Command(_BaseCommand): The coroutine that is executed when the command is called. help: :class:`str` The long help text for the command. - brief: :class:`str` - The short help text for the command. If this is not specified - then the first line of the long help text is used instead. + brief: Optional[:class:`str`] + The short help text for the command. usage: :class:`str` A replacement for arguments in the default help text. - aliases: Union[:class:`list`, :class:`tuple`] + aliases: Union[List[:class:`str`], Tuple[:class:`str`]] The list of aliases the command can be invoked under. enabled: :class:`bool` A boolean that indicates if the command is currently enabled. @@ -384,7 +383,13 @@ class Command(_BaseCommand): return other def copy(self): - """Creates a copy of this command.""" + """Creates a copy of this command. + + Returns + -------- + :class:`Command` + A new instance of this command. + """ ret = self.__class__(self.callback, **self.__original_kwargs__) return self._ensure_assignment_on_copy(ret) @@ -574,7 +579,8 @@ class Command(_BaseCommand): @property def clean_params(self): - """Retrieves the parameter OrderedDict without the context or self parameters. + """OrderedDict[:class:`str`, :class:`inspect.Parameter`]: + Retrieves the parameter OrderedDict without the context or self parameters. Useful for inspecting signature. """ @@ -608,7 +614,7 @@ class Command(_BaseCommand): @property def parents(self): - """:class:`Command`: Retrieves the parents of this command. + """List[:class:`Command`]: Retrieves the parents of this command. If the command has no parents then it returns an empty :class:`list`. @@ -626,7 +632,7 @@ class Command(_BaseCommand): @property def root_parent(self): - """Retrieves the root parent of this command. + """Optional[:class:`Command`]: Retrieves the root parent of this command. If the command has no parents then it returns ``None``. @@ -920,7 +926,7 @@ class Command(_BaseCommand): @property def cog_name(self): - """:class:`str`: The name of the cog this command belongs to. None otherwise.""" + """Optional[:class:`str`]: The name of the cog this command belongs to, if any.""" return type(self.cog).__cog_name__ if self.cog is not None else None @property @@ -1046,7 +1052,7 @@ class GroupMixin: Attributes ----------- all_commands: :class:`dict` - A mapping of command name to :class:`.Command` or subclass + A mapping of command name to :class:`.Command` objects. case_insensitive: :class:`bool` Whether the commands should be case insensitive. Defaults to ``False``. @@ -1069,8 +1075,7 @@ class GroupMixin: self.remove_command(command.name) def add_command(self, command): - """Adds a :class:`.Command` or its subclasses into the internal list - of commands. + """Adds a :class:`.Command` into the internal list of commands. This is usually not called, instead the :meth:`~.GroupMixin.command` or :meth:`~.GroupMixin.group` shortcut decorators are used instead. @@ -1104,7 +1109,7 @@ class GroupMixin: self.all_commands[alias] = command def remove_command(self, name): - """Remove a :class:`.Command` or subclasses from the internal list + """Remove a :class:`.Command` from the internal list of commands. This could also be used as a way to remove aliases. @@ -1116,9 +1121,9 @@ class GroupMixin: Returns -------- - :class:`.Command` or subclass + Optional[:class:`.Command`] The command that was removed. If the name is not valid then - `None` is returned instead. + ``None`` is returned instead. """ command = self.all_commands.pop(name, None) @@ -1147,7 +1152,7 @@ class GroupMixin: yield from command.walk_commands() def get_command(self, name): - """Get a :class:`.Command` or subclasses from the internal list + """Get a :class:`.Command` from the internal list of commands. This could also be used as a way to get aliases. @@ -1163,7 +1168,7 @@ class GroupMixin: Returns -------- - :class:`Command` or subclass + Optional[:class:`Command`] The command that was requested. If not found, returns ``None``. """ @@ -1217,7 +1222,7 @@ class Group(GroupMixin, Command): Attributes ----------- - invoke_without_command: Optional[:class:`bool`] + invoke_without_command: :class:`bool` Indicates if the group callback should begin parsing and invocation only if no subcommand was found. Useful for making it an error handling function to tell the user that @@ -1226,7 +1231,7 @@ class Group(GroupMixin, Command): the group callback will always be invoked first. This means that the checks and the parsing dictated by its parameters will be executed. Defaults to ``False``. - case_insensitive: Optional[:class:`bool`] + case_insensitive: :class:`bool` Indicates if the group's commands should be case insensitive. Defaults to ``False``. """ @@ -1235,7 +1240,13 @@ class Group(GroupMixin, Command): super().__init__(*args, **attrs) def copy(self): - """Creates a copy of this :class:`Group`.""" + """Creates a copy of this :class:`Group`. + + Returns + -------- + :class:`Group` + A new instance of this group. + """ ret = super().copy() for cmd in self.commands: ret.add_command(cmd.copy()) @@ -1856,7 +1867,6 @@ def is_nsfw(): def cooldown(rate, per, type=BucketType.default): """A decorator that adds a cooldown to a :class:`.Command` - or its subclasses. A cooldown allows a command to only be used a specific amount of times in a specific time frame. These cooldowns can be based diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py index 23481a78..34b0b979 100644 --- a/discord/ext/commands/errors.py +++ b/discord/ext/commands/errors.py @@ -90,7 +90,7 @@ class ConversionError(CommandError): ---------- converter: :class:`discord.ext.commands.Converter` The converter that failed. - original + original: :exc:`Exception` The original exception that was raised. You can also get this via the ``__cause__`` attribute. """ diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py index 226e5f6a..21a87396 100644 --- a/discord/ext/commands/help.py +++ b/discord/ext/commands/help.py @@ -155,7 +155,7 @@ class Paginator: @property def pages(self): - """Returns the rendered list of pages.""" + """class:`list`: Returns the rendered list of pages.""" # we have more than just the prefix in our current page if len(self._current_page) > (0 if self.prefix is None else 1): self.close_page() -- cgit v1.2.3