docs: misc fixes/clarifications (#1052)

Co-authored-by: arl <[email protected]>

changelog/635.feature.rst

@@ -1,22 +1 @@
-Clone more attributes in channel ``clone`` methods, and add them as keyword-only parameters to the the respective ``clone`` method on every :class:`abc.GuildChannel` subclass to make in-place edits. The clone methods now support the following fields:
-
-    - :class:`TextChannel`:
-        The :meth:`TextChannel.clone` will now clone :attr:`TextChannel.name`, :attr:`TextChannel.topic`, :attr:`TextChannel.position`, :attr:`TextChannel.nsfw`,
-        :attr:`TextChannel.category`, :attr:`TextChannel.slowmode_delay`, :attr:`TextChannel.type`, :attr:`TextChannel.default_auto_archive_duration`,
-        :attr:`TextChannel.default_thread_slowmode_delay`, :attr:`TextChannel.overwrites` into the newly-cloned TextChannel.
-
-    - :class:`VoiceChannel`:
-        The :meth:`VoiceChannel.clone` will now clone :attr:`VoiceChannel.name`, :attr:`VoiceChannel.bitrate`, :attr:`VoiceChannel.user_limit`, :attr:`VoiceChannel.position`, :attr:`VoiceChannel.category`,
-        :attr:`VoiceChannel.rtc_region`, :attr:`VoiceChannel.video_quality_mode`, :attr:`VoiceChannel.nsfw`, :attr:`VoiceChannel.slowmode_delay`, :attr:`VoiceChannel.overwrites` into the newly-cloned VoiceChannel.
-
-    - :class:`CategoryChannel`:
-        The :meth:`CategoryChannel.clone` will now clone :attr:`CategoryChannel.name`, :attr:`CategoryChannel.position`, :attr:`CategoryChannel.overwrites` into the newly-cloned CategoryChannel.
-
-    - :class:`StageChannel`:
-        The :meth:`StageChannel.clone` will now clone :attr:`StageChannel.name`, :attr:`StageChannel.position`, :attr:`StageChannel.category`, :attr:`StageChannel.rtc_region`, :attr:`StageChannel.bitrate`,
-        :attr:`StageChannel.nsfw`, :attr:`StageChannel.slowmode_delay`, :attr:`StageChannel.video_quality_mode` and :attr:`StageChannel.overwrites` into the newly-cloned StageChannel.
-
-    - :class:`ForumChannel`:
-        The :meth:`ForumChannel.clone` will now clone :attr:`ForumChannel.name`, :attr:`ForumChannel.topic`, :attr:`ForumChannel.position`, :attr:`ForumChannel.nsfw`, :attr:`ForumChannel.category`,
-        :attr:`ForumChannel.slowmode_delay`, :attr:`ForumChannel.default_auto_archive_duration`, :attr:`ForumChannel.default_thread_slowmode_delay`, :attr:`ForumChannel.available_tags`,
-        :attr:`ForumChannel.default_reaction`, :attr:`ForumChannel.default_sort_order`, :attr:`ForumChannel.overwrites` into the newly-cloned ForumChannel.
+Clone more attributes in :meth:`TextChannel.clone`, :meth:`VoiceChannel.clone`, :meth:`StageChannel.clone`, :meth:`CategoryChannel.clone`, and :meth:`ForumChannel.clone`, and add them as keyword-only parameters to make in-place edits. See the specific ``clone`` method's documentation for details.

disnake/abc.py

@@ -1293,13 +1293,13 @@ async def create_invite(
         Parameters
         ----------
         max_age: :class:`int`
-            How long the invite should last in seconds. If it's 0 then the invite
+            How long the invite should last in seconds. If set to ``0``, then the invite
             doesn't expire. Defaults to ``0``.
 
             .. warning::
 
                 If the guild is not a Community guild (has ``COMMUNITY`` in :attr:`.Guild.features`),
-                this must be set to a time between ``1`` and ``2592000`` seconds.
+                this must be set to a number between ``1`` and ``2592000`` seconds.
 
         max_uses: :class:`int`
             How many uses the invite could be used for. If it's 0 then there
@@ -1317,13 +1317,13 @@ async def create_invite(
             .. versionadded:: 2.0
 
         target_user: Optional[:class:`User`]
-            The user whose stream to display for this invite, required if `target_type` is `TargetType.stream`.
+            The user whose stream to display for this invite, required if ``target_type`` is :attr:`.InviteTarget.stream`.
             The user must be streaming in the channel.
 
             .. versionadded:: 2.0
 
         target_application: Optional[:class:`.Snowflake`]
-            The ID of the embedded application for the invite, required if `target_type` is `TargetType.embedded_application`.
+            The ID of the embedded application for the invite, required if ``target_type`` is :attr:`.InviteTarget.embedded_application`.
 
             .. versionadded:: 2.0
 

disnake/channel.py

@@ -509,7 +509,7 @@ async def clone(
 
         .. note::
             The current :attr:`TextChannel.flags` value won't be cloned.
-            This is a discord limitation.
+            This is a Discord limitation.
 
         Parameters
         ----------
@@ -1356,7 +1356,7 @@ async def clone(
 
         .. note::
             The current :attr:`VoiceChannel.flags` value won't be cloned.
-            This is a discord limitation.
+            This is a Discord limitation.
 
         Parameters
         ----------
@@ -2058,7 +2058,7 @@ async def clone(
 
         .. note::
             The current :attr:`StageChannel.flags` value won't be cloned.
-            This is a discord limitation.
+            This is a Discord limitation.
 
         .. warning::
             Currently the ``user_limit`` attribute is not cloned due to a Discord limitation.
@@ -2807,7 +2807,7 @@ async def clone(
 
         .. note::
             The current :attr:`CategoryChannel.flags` value won't be cloned.
-            This is a discord limitation.
+            This is a Discord limitation.
 
         Parameters
         ----------
@@ -3647,7 +3647,7 @@ async def clone(
 
         .. note::
             The current :attr:`ForumChannel.flags` value won't be cloned.
-            This is a discord limitation.
+            This is a Discord limitation.
 
         Parameters
         ----------

disnake/client.py

@@ -1673,6 +1673,9 @@ async def change_presence(
 
         Changes the client's presence.
 
+        .. versionchanged:: 2.0
+            Removed the ``afk`` keyword-only parameter.
+
         .. versionchanged:: 2.6
             Raises :exc:`TypeError` instead of ``InvalidArgument``.
 
@@ -1684,9 +1687,6 @@ async def change_presence(
             game = disnake.Game("with the API")
             await client.change_presence(status=disnake.Status.idle, activity=game)
 
-        .. versionchanged:: 2.0
-            Removed the ``afk`` keyword-only parameter.
-
         Parameters
         ----------
         activity: Optional[:class:`.BaseActivity`]
@@ -1894,6 +1894,11 @@ async def create_guild(
 
         Bot accounts in 10 or more guilds are not allowed to create guilds.
 
+        .. note::
+
+            Using this, you will **not** receive :attr:`.Guild.channels`, :attr:`.Guild.members`,
+            :attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`.
+
         .. versionchanged:: 2.5
             Removed the ``region`` parameter.
 
@@ -1951,6 +1956,11 @@ def guild_builder(self, name: str) -> GuildBuilder:
 
         Bot accounts in 10 or more guilds are not allowed to create guilds.
 
+        .. note::
+
+            Using this, you will **not** receive :attr:`.Guild.channels`, :attr:`.Guild.members`,
+            :attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`.
+
         .. versionadded:: 2.8
 
         Parameters

docs/api/events.rst

@@ -764,7 +764,7 @@ Members
 .. function:: on_member_join(member)
               on_member_remove(member)
 
-    Called when a :class:`Member` leaves or joins a :class:`Guild`.
+    Called when a :class:`Member` joins or leaves a :class:`Guild` (this includes getting kicked/banned).
     If :func:`on_member_remove` is being used then consider using :func:`on_raw_member_remove` which will be called regardless of the cache.
 
     This requires :attr:`Intents.members` to be enabled.
@@ -796,7 +796,7 @@ Members
 
 .. function:: on_raw_member_remove(payload)
 
-    Called when a member leaves a :class:`Guild`.
+    Called when a member leaves a :class:`Guild` (this includes getting kicked/banned).
     Unlike :func:`on_member_remove`, this is called regardless of the member cache.
 
     .. versionadded:: 2.6