Fix and add documentation

5 files changed, 45 insertions, 9 deletions

diff --git a/discord/ext/commands/cog.py b/discord/ext/commands/cog.py
index 50573f49..2a836daa 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 12bb0646..f3d7b257 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 1d044edd..fc1b932c 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 6a9eb6af..beec98f5 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 c7143317..5d567325 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