diff --git a/discord/abc.py b/discord/abc.py
index ad148f745..4024334d1 100644
--- a/discord/abc.py
+++ b/discord/abc.py
@@ -698,6 +698,11 @@ class GuildChannel:
You do not have the proper permissions to create this channel.
~discord.HTTPException
Creating the channel failed.
+
+ Returns
+ --------
+ :class:`.abc.GuildChannel`
+ The channel that was created.
"""
raise NotImplementedError
diff --git a/discord/channel.py b/discord/channel.py
index c02c00f36..c3ccbe0ff 100644
--- a/discord/channel.py
+++ b/discord/channel.py
@@ -158,11 +158,11 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
return [m for m in self.guild.members if self.permissions_for(m).read_messages]
def is_nsfw(self):
- """Checks if the channel is NSFW."""
+ """:class:`bool`: Checks if the channel is NSFW."""
return self.nsfw
def is_news(self):
- """Checks if the channel is a news channel."""
+ """:class:`bool`: Checks if the channel is a news channel."""
return self._type == ChannelType.news.value
@property
@@ -757,7 +757,7 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
return ChannelType.category
def is_nsfw(self):
- """Checks if the category is NSFW."""
+ """:class:`bool`: Checks if the category is NSFW."""
return self.nsfw
async def clone(self, *, name=None, reason=None):
@@ -933,7 +933,7 @@ class StoreChannel(discord.abc.GuildChannel, Hashable):
permissions_for.__doc__ = discord.abc.GuildChannel.permissions_for.__doc__
def is_nsfw(self):
- """Checks if the channel is NSFW."""
+ """:class:`bool`: Checks if the channel is NSFW."""
return self.nsfw
async def clone(self, *, name=None, reason=None):
diff --git a/discord/client.py b/discord/client.py
index f0c1fee6e..9bc5dd120 100644
--- a/discord/client.py
+++ b/discord/client.py
@@ -303,7 +303,7 @@ class Client:
return self._connection.voice_clients
def is_ready(self):
- """Specifies if the client's internal cache is ready for use."""
+ """:class:`bool`: Specifies if the client's internal cache is ready for use."""
return self._ready.is_set()
async def _run_event(self, coro, event_name, *args, **kwargs):
@@ -683,7 +683,7 @@ class Client:
# properties
def is_closed(self):
- """Indicates if the websocket connection is closed."""
+ """:class:`bool`: Indicates if the websocket connection is closed."""
return self._closed
@property
@@ -800,6 +800,11 @@ class Client:
Just because you receive a :class:`.abc.GuildChannel` does not mean that
you can communicate in said channel. :meth:`.abc.GuildChannel.permissions_for` should
be used for that.
+
+ Yields
+ ------
+ :class:`.abc.GuildChannel`
+ A channel the client can 'access'.
"""
for guild in self.guilds:
@@ -814,6 +819,11 @@ class Client:
for guild in client.guilds:
for member in guild.members:
yield member
+
+ Yields
+ ------
+ :class:`.Member`
+ A member the client can see.
"""
for guild in self.guilds:
for member in guild.members:
diff --git a/discord/ext/commands/cog.py b/discord/ext/commands/cog.py
index 50573f49b..2a836daa6 100644
--- a/discord/ext/commands/cog.py
+++ b/discord/ext/commands/cog.py
@@ -216,7 +216,13 @@ class Cog(metaclass=CogMeta):
return cleaned
def walk_commands(self):
- """An iterator that recursively walks through this cog's commands and subcommands."""
+ """An iterator that recursively walks through this cog's commands and subcommands.
+
+ Yields
+ ------
+ Union[:class:`.Command`, :class:`.Group`]
+ A command or group from the cog.
+ """
from .core import GroupMixin
for command in self.__cog_commands__:
if command.parent is None:
diff --git a/discord/ext/commands/converter.py b/discord/ext/commands/converter.py
index 12bb06466..f3d7b2571 100644
--- a/discord/ext/commands/converter.py
+++ b/discord/ext/commands/converter.py
@@ -362,6 +362,7 @@ class CategoryChannelConverter(IDConverter):
class ColourConverter(Converter):
"""Converts to a :class:`~discord.Colour`.
+
.. versionchanged:: 1.5
Add an alias named ColorConverter
diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py
index 1d044edd8..fc1b932c2 100644
--- a/discord/ext/commands/core.py
+++ b/discord/ext/commands/core.py
@@ -1180,6 +1180,11 @@ class GroupMixin:
.. versionchanged:: 1.4
Duplicates due to aliases are no longer returned
+
+ Yields
+ ------
+ Union[:class:`.Command`, :class:`.Group`]
+ A command or group from the internal list of commands.
"""
for command in self.commands:
yield command
@@ -1233,7 +1238,7 @@ class GroupMixin:
Returns
--------
Callable[..., :class:`Command`]
- A decorator that converts the provided method into a Command, adds it to the bot, then returns it
+ A decorator that converts the provided method into a Command, adds it to the bot, then returns it.
"""
def decorator(func):
kwargs.setdefault('parent', self)
@@ -1246,6 +1251,11 @@ class GroupMixin:
def group(self, *args, **kwargs):
"""A shortcut decorator that invokes :func:`.group` and adds it to
the internal command list via :meth:`~.GroupMixin.add_command`.
+
+ Returns
+ --------
+ Callable[..., :class:`Group`]
+ A decorator that converts the provided method into a Group, adds it to the bot, then returns it.
"""
def decorator(func):
kwargs.setdefault('parent', self)
diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py
index 6a9eb6afb..beec98f58 100644
--- a/discord/ext/commands/errors.py
+++ b/discord/ext/commands/errors.py
@@ -273,7 +273,7 @@ class ChannelNotReadable(BadArgument):
Attributes
-----------
- argument: :class:`Channel`
+ argument: :class:`.abc.GuildChannel`
The channel supplied by the caller that was not readable
"""
def __init__(self, argument):
@@ -403,7 +403,7 @@ class CommandInvokeError(CommandError):
Attributes
-----------
- original
+ original: :exc:`Exception`
The original exception that was raised. You can also get this via
the ``__cause__`` attribute.
"""
@@ -438,7 +438,7 @@ class MaxConcurrencyReached(CommandError):
------------
number: :class:`int`
The maximum number of concurrent invokers allowed.
- per: :class:`BucketType`
+ per: :class:`.BucketType`
The bucket type passed to the :func:`.max_concurrency` decorator.
"""
diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py
index c71433179..5d5673254 100644
--- a/discord/ext/commands/help.py
+++ b/discord/ext/commands/help.py
@@ -155,7 +155,7 @@ class Paginator:
@property
def pages(self):
- """class:`list`: Returns the rendered list of pages."""
+ """List[:class:`str`]: 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()
@@ -381,7 +381,7 @@ class HelpCommand:
@property
def clean_prefix(self):
- """The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``."""
+ """:class:`str`: The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``."""
user = self.context.guild.me if self.context.guild else self.context.bot.user
# this breaks if the prefix mention is not the bot itself but I
# consider this to be an *incredibly* strange use case. I'd rather go
@@ -441,6 +441,11 @@ class HelpCommand:
"""Removes mentions from the string to prevent abuse.
This includes ``@everyone``, ``@here``, member mentions and role mentions.
+
+ Returns
+ -------
+ :class:`str`
+ The string with mentions removed.
"""
def replace(obj, *, transforms=self.MENTION_TRANSFORMS):
@@ -603,6 +608,11 @@ class HelpCommand:
You can override this method to customise the behaviour.
By default this returns the context's channel.
+
+ Returns
+ -------
+ :class:`.abc.Messageable`
+ The destination where the help command will be output.
"""
return self.context.channel
@@ -911,13 +921,13 @@ class DefaultHelpCommand(HelpCommand):
super().__init__(**options)
def shorten_text(self, text):
- """Shortens text to fit into the :attr:`width`."""
+ """:class:`str`: Shortens text to fit into the :attr:`width`."""
if len(text) > self.width:
return text[:self.width - 3] + '...'
return text
def get_ending_note(self):
- """Returns help command's ending note. This is mainly useful to override for i18n purposes."""
+ """:class:`str`: Returns help command's ending note. This is mainly useful to override for i18n purposes."""
command_name = self.invoked_with
return "Type {0}{1} command for more info on a command.\n" \
"You can also type {0}{1} category for more info on a category.".format(self.clean_prefix, command_name)
@@ -1122,6 +1132,10 @@ class MinimalHelpCommand(HelpCommand):
Use `{prefix}{command_name} [command]` for more info on a command.
You can also use `{prefix}{command_name} [category]` for more info on a category.
+ Returns
+ -------
+ :class:`str`
+ The help command opening note.
"""
command_name = self.invoked_with
return "Use `{0}{1} [command]` for more info on a command.\n" \
@@ -1134,6 +1148,11 @@ class MinimalHelpCommand(HelpCommand):
"""Return the help command's ending note. This is mainly useful to override for i18n purposes.
The default implementation does nothing.
+
+ Returns
+ -------
+ :class:`str`
+ The help command ending note.
"""
return None
diff --git a/discord/member.py b/discord/member.py
index b9d1ffa7f..dbcbc492d 100644
--- a/discord/member.py
+++ b/discord/member.py
@@ -309,7 +309,7 @@ class Member(discord.abc.Messageable, _BaseUser):
return try_enum(Status, self._client_status.get('web', 'offline'))
def is_on_mobile(self):
- """A helper function that determines if a member is active on a mobile device."""
+ """:class:`bool`: A helper function that determines if a member is active on a mobile device."""
return 'mobile' in self._client_status
@property
@@ -395,6 +395,11 @@ class Member(discord.abc.Messageable, _BaseUser):
-----------
message: :class:`Message`
The message to check if you're mentioned in.
+
+ Returns
+ -------
+ :class:`bool`
+ Indicates if the member is mentioned in the message.
"""
if message.guild is None or message.guild.id != self.guild.id:
return False
diff --git a/discord/message.py b/discord/message.py
index 8e6fdde7b..4ba2a826c 100644
--- a/discord/message.py
+++ b/discord/message.py
@@ -613,7 +613,7 @@ class Message:
@utils.cached_slot_property('_cs_clean_content')
def clean_content(self):
- """A property that returns the content in a "cleaned up"
+ """:class:`str`: A property that returns the content in a "cleaned up"
manner. This basically means that mentions are transformed
into the way the client shows it. e.g. ``<#id>`` will transform
into ``#name``.
diff --git a/discord/partial_emoji.py b/discord/partial_emoji.py
index 42f38a489..1eebf5dac 100644
--- a/discord/partial_emoji.py
+++ b/discord/partial_emoji.py
@@ -124,11 +124,11 @@ class PartialEmoji(_EmojiTag):
return hash((self.id, self.name))
def is_custom_emoji(self):
- """Checks if this is a custom non-Unicode emoji."""
+ """:class:`bool`: Checks if this is a custom non-Unicode emoji."""
return self.id is not None
def is_unicode_emoji(self):
- """Checks if this is a Unicode emoji."""
+ """:class:`bool`: Checks if this is a Unicode emoji."""
return self.id is None
def _as_reaction(self):
diff --git a/discord/permissions.py b/discord/permissions.py
index d550bca69..55e26f911 100644
--- a/discord/permissions.py
+++ b/discord/permissions.py
@@ -495,10 +495,7 @@ class PermissionOverwrite:
self._values[key] = value
def pair(self):
- """Returns the (allow, deny) pair from this overwrite.
-
- The value of these pairs is :class:`Permissions`.
- """
+ """Tuple[:class:`Permissions`, :class:`Permissions`]: Returns the (allow, deny) pair from this overwrite."""
allow = Permissions.none()
deny = Permissions.none()
@@ -530,6 +527,11 @@ class PermissionOverwrite:
An empty permission overwrite is one that has no overwrites set
to ``True`` or ``False``.
+
+ Returns
+ -------
+ :class:`bool`
+ Indicates if the overwrite is empty.
"""
return all(x is None for x in self._values.values())
diff --git a/discord/role.py b/discord/role.py
index 24ae3bdd8..882f346e4 100644
--- a/discord/role.py
+++ b/discord/role.py
@@ -148,7 +148,7 @@ class Role(Hashable):
self.mentionable = data.get('mentionable', False)
def is_default(self):
- """Checks if the role is the default role."""
+ """:class:`bool`: Checks if the role is the default role."""
return self.guild.id == self.id
@property
diff --git a/discord/user.py b/discord/user.py
index 903a0b002..690cbce9f 100644
--- a/discord/user.py
+++ b/discord/user.py
@@ -150,7 +150,7 @@ class BaseUser(_BaseUser):
return self.avatar_url_as(format=None, size=1024)
def is_avatar_animated(self):
- """Indicates if the user has an animated avatar."""
+ """:class:`bool`: Indicates if the user has an animated avatar."""
return bool(self.avatar and self.avatar.startswith('a_'))
def avatar_url_as(self, *, format=None, static_format='webp', size=1024):
@@ -262,6 +262,11 @@ class BaseUser(_BaseUser):
-----------
message: :class:`Message`
The message to check if you're mentioned in.
+
+ Returns
+ -------
+ :class:`bool`
+ Indicates if the user is mentioned in the message.
"""
if message.mention_everyone:
@@ -706,6 +711,11 @@ class User(BaseUser, discord.abc.Messageable):
This should be rarely called, as this is done transparently for most
people.
+
+ Returns
+ -------
+ :class:`.DMChannel`
+ The channel that was created.
"""
found = self.dm_channel
if found is not None:
@@ -751,7 +761,7 @@ class User(BaseUser, discord.abc.Messageable):
return [User(state=state, data=friend) for friend in mutuals]
def is_friend(self):
- """Checks if the user is your friend.
+ """:class:`bool`: Checks if the user is your friend.
.. note::
@@ -763,7 +773,7 @@ class User(BaseUser, discord.abc.Messageable):
return r.type is RelationshipType.friend
def is_blocked(self):
- """Checks if the user is blocked.
+ """:class:`bool`: Checks if the user is blocked.
.. note::
diff --git a/docs/conf.py b/docs/conf.py
index a16c34cf7..d87049ac3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -50,7 +50,7 @@ extlinks = {
# Links used for cross-referencing stuff in other documentation
intersphinx_mapping = {
'py': ('https://docs.python.org/3', None),
- 'aio': ('https://aiohttp.readthedocs.io/en/stable/', None),
+ 'aio': ('https://docs.aiohttp.org/en/stable/', None),
'req': ('http://docs.python-requests.org/en/latest/', 'requests.inv')
}
@@ -318,6 +318,6 @@ texinfo_documents = [
#texinfo_no_detailmenu = False
def setup(app):
- app.add_javascript('custom.js')
+ app.add_js_file('custom.js')
if app.config.language == 'ja':
app.config.intersphinx_mapping['py'] = ('https://docs.python.org/ja/3', None)