Improve documentation

discord/asset.py

@@ -163,6 +163,13 @@ async def read(self):
 
         .. versionadded:: 1.1.0
 
+        Parameters
+        -----------
+        fp: Union[:class:`io.BufferedIOBase`, :class:`os.PathLike`]
+            Same as in :meth:`Attachment.save`.
+        seek_begin: :class:`bool`
+            Same as in :meth:`Attachment.save`.
+
         Raises
         ------
         DiscordException

discord/audit_logs.py

@@ -269,7 +269,7 @@ def __repr__(self):
 
     @utils.cached_property
     def created_at(self):
-        """Returns the entry's creation time in UTC."""
+        """:class:`datetime.datetime`: Returns the entry's creation time in UTC."""
         return utils.snowflake_time(self.id)
 
     @utils.cached_property

discord/backoff.py

@@ -42,10 +42,10 @@ class ExponentialBackoff:
     Parameters
     ----------
     base: :class:`int`
-        The base delay in seconds.  The first retry-delay will be up to
+        The base delay in seconds. The first retry-delay will be up to
         this many seconds.
     integral: :class:`bool`
-        Set to True if whole periods of base is desirable, otherwise any
+        Set to ``True`` if whole periods of base is desirable, otherwise any
         number in between may be returned.
     """
 

discord/calls.py

@@ -38,7 +38,7 @@ class CallMessage:
 
     Attributes
     -----------
-    ended_timestamp: Optional[datetime.datetime]
+    ended_timestamp: Optional[:class:`datetime.datetime`]
         A naive UTC datetime object that represents the time that the call has ended.
     participants: List[:class:`User`]
         The list of users that are participating in this call.
@@ -70,7 +70,7 @@ def duration(self):
 
         Returns
         ---------
-        datetime.timedelta
+        :class:`datetime.timedelta`
             The timedelta object representing the duration.
         """
         if self.ended_timestamp is None:
@@ -122,7 +122,7 @@ def _update_voice_state(self, data):
 
     @property
     def connected(self):
-        """A property that returns the :class:`list` of :class:`User` that are currently in this call."""
+        """List[:class:`User`]: A property that returns all users that are currently in this call."""
         ret = [u for u in self.channel.recipients if self.voice_state_for(u) is not None]
         me = self.channel.me
         if self.voice_state_for(me) is not None:

discord/channel.py

@@ -149,7 +149,7 @@ def permissions_for(self, member):
 
     @property
     def members(self):
-        """Returns a :class:`list` of :class:`Member` that can see this channel."""
+        """List[:class:`Member`]: Returns all members that can see this channel."""
         return [m for m in self.guild.members if self.permissions_for(m).read_messages]
 
     def is_nsfw(self):
@@ -313,22 +313,22 @@ def is_me(m):
         limit: Optional[:class:`int`]
             The number of messages to search through. This is not the number
             of messages that will be deleted, though it can be.
-        check: predicate
+        check: Callable[[:class:`Message`], :class:`bool`]
             The function used to check if a message should be deleted.
             It must take a :class:`Message` as its sole parameter.
-        before
+        before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
             Same as ``before`` in :meth:`history`.
-        after
+        after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
             Same as ``after`` in :meth:`history`.
-        around
+        around: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
             Same as ``around`` in :meth:`history`.
-        oldest_first
+        oldest_first: Optional[:class:`bool`]
             Same as ``oldest_first`` in :meth:`history`.
-        bulk: :class:`bool`
-            If True, use bulk delete. bulk=False is useful for mass-deleting
-            a bot's own messages without manage_messages. When True, will fall
-            back to single delete if current account is a user bot, or if
-            messages are older than two weeks.
+        bulk: class:`bool`
+            If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting
+            a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will
+            fall back to single delete if current account is a user bot, or if messages are
+            older than two weeks.
 
         Raises
         -------
@@ -534,7 +534,7 @@ def _sorting_bucket(self):
 
     @property
     def members(self):
-        """Returns a list of :class:`Member` that are currently inside this voice channel."""
+        """List[:class:`Member`]: Returns all members that are currently inside this voice channel."""
         ret = []
         for user_id, state in self.guild._voice_states.items():
             if state.channel.id == self.id:
@@ -943,10 +943,10 @@ def permissions_for(self, user=None):
 
         Actual direct messages do not really have the concept of permissions.
 
-        This returns all the Text related permissions set to true except:
+        This returns all the Text related permissions set to ``True`` except:
 
-        - send_tts_messages: You cannot send TTS messages in a DM.
-        - manage_messages: You cannot delete others messages in a DM.
+        - :attr:`~Permissions.send_tts_messages`: You cannot send TTS messages in a DM.
+        - :attr:`~Permissions.manage_messages`: You cannot delete others messages in a DM.
 
         Parameters
         -----------
@@ -988,7 +988,7 @@ class GroupChannel(discord.abc.Messageable, Hashable):
 
     Attributes
     ----------
-    recipients: :class:`list` of :class:`User`
+    recipients: List[:class:`User`]
         The users you are participating with in the group channel.
     me: :class:`ClientUser`
         The user presenting yourself.
@@ -1051,7 +1051,7 @@ def icon_url(self):
 
     @property
     def created_at(self):
-        """Returns the channel's creation time in UTC."""
+        """:class:`datetime.datetime`: Returns the channel's creation time in UTC."""
         return utils.snowflake_time(self.id)
 
     def permissions_for(self, user):
@@ -1061,7 +1061,7 @@ def permissions_for(self, user):
 
         Actual direct messages do not really have the concept of permissions.
 
-        This returns all the Text related permissions set to true except:
+        This returns all the Text related permissions set to ``True`` except:
 
         - send_tts_messages: You cannot send TTS messages in a DM.
         - manage_messages: You cannot delete others messages in a DM.