Fix and add documentation

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
 

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):

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:

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:

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
 

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)

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

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
 

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

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``.

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):

discord/permissions.py

@@ -495,10 +495,7 @@ class PermissionOverwrite:
         self._values[key] = value
 
     def pair(self):
-        """Returns the (allow, deny) pair from this overwrite.
+        """Tuple[:class:`Permissions`, :class:`Permissions`]: Returns the (allow, deny) pair from this overwrite."""
-
-        The value of these pairs is :class:`Permissions`.
-        """
 
         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())
 

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

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

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)