mirrors/discord.py
1
0
Fork 0
mirror of https://github.com/Rapptz/discord.py.git synced 2025-09-08 10:53:10 +00:00
Code Issues Projects Releases Wiki Activity

Fix various inconsistencies within the documentation (#5067)

Browse Source
This commit is contained in:
Sebastian Law
2020-06-28 00:45:58 -07:00
committed by GitHub
parent f94b00cb48
commit b4b953bfc6
24 changed files with 378 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
discord/ext/commands/bot.py
View File

@ -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
"""

22
discord/ext/commands/cog.py
View File

@ -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 <coroutine>`]]
The listeners defined in this cog.
"""
return [(name, getattr(self, method_name)) for name, method_name in self.__cog_listeners__]
@classmethod

32
discord/ext/commands/context.py
View File

@ -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

52
discord/ext/commands/core.py
View File

@ -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

2
discord/ext/commands/errors.py
View File

@ -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.
"""

2
discord/ext/commands/help.py
View File

@ -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()