Improve documentation

1 files changed, 46 insertions, 40 deletions

diff --git a/discord/permissions.py b/discord/permissions.py
index 6cee27a6..45db34f5 100644
--- a/discord/permissions.py
+++ b/discord/permissions.py
@@ -97,25 +97,25 @@ class Permissions:
         return self._perm_iterator()
 
     def is_subset(self, other):
-        """Returns True if self has the same or fewer permissions as other."""
+        """Returns ``True`` if self has the same or fewer permissions as other."""
         if isinstance(other, Permissions):
             return (self.value & other.value) == self.value
         else:
             raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__))
 
     def is_superset(self, other):
-        """Returns True if self has the same or more permissions as other."""
+        """Returns ``True`` if self has the same or more permissions as other."""
         if isinstance(other, Permissions):
             return (self.value | other.value) == self.value
         else:
             raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__))
 
     def is_strict_subset(self, other):
-        """Returns True if the permissions on other are a strict subset of those on self."""
+        """Returns ``True`` if the permissions on other are a strict subset of those on self."""
         return self.is_subset(other) and self != other
 
     def is_strict_superset(self, other):
-        """Returns True if the permissions on other are a strict superset of those on self."""
+        """Returns ``True`` if the permissions on other are a strict superset of those on self."""
         return self.is_superset(other) and self != other
 
     __le__ = is_subset
@@ -126,7 +126,7 @@ class Permissions:
     @classmethod
     def none(cls):
         """A factory method that creates a :class:`Permissions` with all
-        permissions set to False."""
+        permissions set to ``False``."""
         return cls(0)
 
     @classmethod
@@ -138,7 +138,7 @@ class Permissions:
     @classmethod
     def all_channel(cls):
         """A :class:`Permissions` with all channel-specific permissions set to
-        True and the guild-specific ones set to False. The guild-specific
+        ``True`` and the guild-specific ones set to ``False``. The guild-specific
         permissions are currently:
 
         - manage_guild
@@ -153,21 +153,22 @@ class Permissions:
     @classmethod
     def general(cls):
         """A factory method that creates a :class:`Permissions` with all
-        "General" permissions from the official Discord UI set to True."""
+        "General" permissions from the official Discord UI set to ``True``."""
         return cls(0b01111100000000000000000010111111)
 
     @classmethod
     def text(cls):
         """A factory method that creates a :class:`Permissions` with all
-        "Text" permissions from the official Discord UI set to True."""
+        "Text" permissions from the official Discord UI set to ``True``."""
         return cls(0b00000000000001111111110001000000)
 
     @classmethod
     def voice(cls):
         """A factory method that creates a :class:`Permissions` with all
-        "Voice" permissions from the official Discord UI set to True."""
+        "Voice" permissions from the official Discord UI set to ``True``."""
         return cls(0b00000011111100000000001100000000)
 
+
     def update(self, **kwargs):
         r"""Bulk updates this permission object.
 
@@ -217,7 +218,7 @@ class Permissions:
 
     @property
     def create_instant_invite(self):
-        """Returns True if the user can create instant invites."""
+        """:class:`bool`: Returns ``True`` if the user can create instant invites."""
         return self._bit(0)
 
     @create_instant_invite.setter
@@ -226,7 +227,7 @@ class Permissions:
 
     @property
     def kick_members(self):
-        """Returns True if the user can kick users from the guild."""
+        """:class:`bool`: Returns ``True`` if the user can kick users from the guild."""
         return self._bit(1)
 
     @kick_members.setter
@@ -235,7 +236,7 @@ class Permissions:
 
     @property
     def ban_members(self):
-        """Returns True if a user can ban users from the guild."""
+        """:class:`bool`: Returns ``True`` if a user can ban users from the guild."""
         return self._bit(2)
 
     @ban_members.setter
@@ -244,7 +245,7 @@ class Permissions:
 
     @property
     def administrator(self):
-        """Returns True if a user is an administrator. This role overrides all other permissions.
+        """:class:`bool`: Returns ``True`` if a user is an administrator. This role overrides all other permissions.
 
         This also bypasses all channel-specific overrides.
         """
@@ -256,7 +257,7 @@ class Permissions:
 
     @property
     def manage_channels(self):
-        """Returns True if a user can edit, delete, or create channels in the guild.
+        """:class:`bool`: Returns ``True`` if a user can edit, delete, or create channels in the guild.
 
         This also corresponds to the "Manage Channel" channel-specific override."""
         return self._bit(4)
@@ -267,7 +268,7 @@ class Permissions:
 
     @property
     def manage_guild(self):
-        """Returns True if a user can edit guild properties."""
+        """:class:`bool`: Returns ``True`` if a user can edit guild properties."""
         return self._bit(5)
 
     @manage_guild.setter
@@ -276,7 +277,7 @@ class Permissions:
 
     @property
     def add_reactions(self):
-        """Returns True if a user can add reactions to messages."""
+        """:class:`bool`: Returns ``True`` if a user can add reactions to messages."""
         return self._bit(6)
 
     @add_reactions.setter
@@ -285,7 +286,7 @@ class Permissions:
 
     @property
     def view_audit_log(self):
-        """Returns True if a user can view the guild's audit log."""
+        """:class:`bool`: Returns ``True`` if a user can view the guild's audit log."""
         return self._bit(7)
 
     @view_audit_log.setter
@@ -294,7 +295,7 @@ class Permissions:
 
     @property
     def priority_speaker(self):
-        """Returns True if a user can be more easily heard while talking."""
+        """:class:`bool`: Returns ``True`` if a user can be more easily heard while talking."""
         return self._bit(8)
 
     @priority_speaker.setter
@@ -303,7 +304,7 @@ class Permissions:
 
     @property
     def stream(self):
-        """Returns ``True`` if a user can stream in a voice channel."""
+        """:class:`bool`: Returns ``True`` if a user can stream in a voice channel."""
         return self._bit(9)
 
     @stream.setter
@@ -312,7 +313,7 @@ class Permissions:
 
     @property
     def read_messages(self):
-        """Returns True if a user can read messages from all or specific text channels."""
+        """:class:`bool`: Returns ``True`` if a user can read messages from all or specific text channels."""
         return self._bit(10)
 
     @read_messages.setter
@@ -321,7 +322,7 @@ class Permissions:
 
     @property
     def send_messages(self):
-        """Returns True if a user can send messages from all or specific text channels."""
+        """:class:`bool`: Returns ``True`` if a user can send messages from all or specific text channels."""
         return self._bit(11)
 
     @send_messages.setter
@@ -330,7 +331,7 @@ class Permissions:
 
     @property
     def send_tts_messages(self):
-        """Returns True if a user can send TTS messages from all or specific text channels."""
+        """:class:`bool`: Returns ``True`` if a user can send TTS messages from all or specific text channels."""
         return self._bit(12)
 
     @send_tts_messages.setter
@@ -339,7 +340,12 @@ class Permissions:
 
     @property
     def manage_messages(self):
-        """Returns True if a user can delete or pin messages in a text channel. Note that there are currently no ways to edit other people's messages."""
+        """:class:`bool`: Returns ``True`` if a user can delete or pin messages in a text channel.
+
+        .. note::
+
+            Note that there are currently no ways to edit other people's messages.
+        """
         return self._bit(13)
 
     @manage_messages.setter
@@ -348,7 +354,7 @@ class Permissions:
 
     @property
     def embed_links(self):
-        """Returns True if a user's messages will automatically be embedded by Discord."""
+        """:class:`bool`: Returns ``True`` if a user's messages will automatically be embedded by Discord."""
         return self._bit(14)
 
     @embed_links.setter
@@ -357,7 +363,7 @@ class Permissions:
 
     @property
     def attach_files(self):
-        """Returns True if a user can send files in their messages."""
+        """:class:`bool`: Returns ``True`` if a user can send files in their messages."""
         return self._bit(15)
 
     @attach_files.setter
@@ -366,7 +372,7 @@ class Permissions:
 
     @property
     def read_message_history(self):
-        """Returns True if a user can read a text channel's previous messages."""
+        """:class:`bool`: Returns ``True`` if a user can read a text channel's previous messages."""
         return self._bit(16)
 
     @read_message_history.setter
@@ -375,7 +381,7 @@ class Permissions:
 
     @property
     def mention_everyone(self):
-        """Returns True if a user's @everyone or @here will mention everyone in the text channel."""
+        """:class:`bool`: Returns ``True`` if a user's @everyone or @here will mention everyone in the text channel."""
         return self._bit(17)
 
     @mention_everyone.setter
@@ -384,7 +390,7 @@ class Permissions:
 
     @property
     def external_emojis(self):
-        """Returns True if a user can use emojis from other guilds."""
+        """:class:`bool`: Returns ``True`` if a user can use emojis from other guilds."""
         return self._bit(18)
 
     @external_emojis.setter
@@ -395,7 +401,7 @@ class Permissions:
 
     @property
     def connect(self):
-        """Returns True if a user can connect to a voice channel."""
+        """:class:`bool`: Returns ``True`` if a user can connect to a voice channel."""
         return self._bit(20)
 
     @connect.setter
@@ -404,7 +410,7 @@ class Permissions:
 
     @property
     def speak(self):
-        """Returns True if a user can speak in a voice channel."""
+        """:class:`bool`: Returns ``True`` if a user can speak in a voice channel."""
         return self._bit(21)
 
     @speak.setter
@@ -413,7 +419,7 @@ class Permissions:
 
     @property
     def mute_members(self):
-        """Returns True if a user can mute other users."""
+        """:class:`bool`: Returns ``True`` if a user can mute other users."""
         return self._bit(22)
 
     @mute_members.setter
@@ -422,7 +428,7 @@ class Permissions:
 
     @property
     def deafen_members(self):
-        """Returns True if a user can deafen other users."""
+        """:class:`bool`: Returns ``True`` if a user can deafen other users."""
         return self._bit(23)
 
     @deafen_members.setter
@@ -431,7 +437,7 @@ class Permissions:
 
     @property
     def move_members(self):
-        """Returns True if a user can move users between other voice channels."""
+        """:class:`bool`: Returns ``True`` if a user can move users between other voice channels."""
         return self._bit(24)
 
     @move_members.setter
@@ -440,7 +446,7 @@ class Permissions:
 
     @property
     def use_voice_activation(self):
-        """Returns True if a user can use voice activation in voice channels."""
+        """:class:`bool`: Returns ``True`` if a user can use voice activation in voice channels."""
         return self._bit(25)
 
     @use_voice_activation.setter
@@ -449,7 +455,7 @@ class Permissions:
 
     @property
     def change_nickname(self):
-        """Returns True if a user can change their nickname in the guild."""
+        """:class:`bool`: Returns ``True`` if a user can change their nickname in the guild."""
         return self._bit(26)
 
     @change_nickname.setter
@@ -458,7 +464,7 @@ class Permissions:
 
     @property
     def manage_nicknames(self):
-        """Returns True if a user can change other user's nickname in the guild."""
+        """:class:`bool`: Returns ``True`` if a user can change other user's nickname in the guild."""
         return self._bit(27)
 
     @manage_nicknames.setter
@@ -467,7 +473,7 @@ class Permissions:
 
     @property
     def manage_roles(self):
-        """Returns True if a user can create or edit roles less than their role's position.
+        """:class:`bool`: Returns ``True`` if a user can create or edit roles less than their role's position.
 
         This also corresponds to the "Manage Permissions" channel-specific override.
         """
@@ -479,7 +485,7 @@ class Permissions:
 
     @property
     def manage_webhooks(self):
-        """Returns True if a user can create, edit, or delete webhooks."""
+        """:class:`bool`: Returns ``True`` if a user can create, edit, or delete webhooks."""
         return self._bit(29)
 
     @manage_webhooks.setter
@@ -488,7 +494,7 @@ class Permissions:
 
     @property
     def manage_emojis(self):
-        """Returns True if a user can create, edit, or delete emojis."""
+        """:class:`bool`: Returns ``True`` if a user can create, edit, or delete emojis."""
         return self._bit(30)
 
     @manage_emojis.setter
@@ -604,7 +610,7 @@ class PermissionOverwrite:
         """Checks if the permission overwrite is currently empty.
 
         An empty permission overwrite is one that has no overwrites set
-        to True or False.
+        to ``True`` or ``False``.
         """
         return all(x is None for x in self._values.values())