docs(emoji): misc documentation fixes for app emojis (#1388)

Signed-off-by: vi <8530778+shiftinv@users.noreply.github.com>
Signed-off-by: arielle <me@arielle.codes>
Co-authored-by: arielle <me@arielle.codes>

Author: shiftinv

changelog/1223.feature.rst

@@ -1,3 +1,3 @@
-Add support to :class:`.Emoji` to represent application emojis.
-New methods on :class:`Client`: :meth:`Client.fetch_application_emoji`, :meth:`Client.fetch_application_emojis` and :meth:`Client.create_application_emoji`.
-New attributes on :class:`.Emoji`: :attr:`Emoji.application_id`, :attr:`Emoji.is_guild_emoji` and :attr:`Emoji.is_app_emoji`.
+Add support to :class:`.Emoji` to represent application-owned emojis.
+- New methods on :class:`Client`: :meth:`Client.fetch_application_emoji`, :meth:`Client.fetch_application_emojis` and :meth:`Client.create_application_emoji`.
+- New attributes on :class:`.Emoji`: :attr:`Emoji.application_id`, :attr:`Emoji.is_guild_emoji` and :attr:`Emoji.is_app_emoji`.

changelog/1388.feature.rst

@@ -0,0 +1,3 @@
+Add support to :class:`.Emoji` to represent application-owned emojis.
+- New methods on :class:`Client`: :meth:`Client.fetch_application_emoji`, :meth:`Client.fetch_application_emojis` and :meth:`Client.create_application_emoji`.
+- New attributes on :class:`.Emoji`: :attr:`Emoji.application_id`, :attr:`Emoji.is_guild_emoji` and :attr:`Emoji.is_app_emoji`.

disnake/client.py

@@ -2439,8 +2439,8 @@ async def fetch_application_emoji(self, emoji_id: int) -> Emoji:
         ------
         NotFound
             The app emoji couldn't be found.
-        Forbidden
-            You are not allowed to get the app emoji.
+        HTTPException
+            An error occurred fetching the app emoji.
 
         Returns
         -------
@@ -2469,10 +2469,8 @@ async def create_application_emoji(self, *, name: str, image: AssetBytes) -> Emo
         ------
         NotFound
             The ``image`` asset couldn't be found.
-        Forbidden
-            You are not allowed to create app emojis.
         HTTPException
-            An error occurred creating an app emoji.
+            An error occurred creating the app emoji.
         TypeError
             The ``image`` asset is a lottie sticker (see :func:`Sticker.read <disnake.Sticker.read>`).
         ValueError
@@ -2496,10 +2494,8 @@ async def fetch_application_emojis(self) -> List[Emoji]:
 
         Raises
         ------
-        NotFound
-            The app emojis for this application ID couldn't be found.
-        Forbidden
-            You are not allowed to get app emojis.
+        HTTPException
+            An error occurred fetching the app emojis.
 
         Returns
         -------

disnake/emoji.py

@@ -54,7 +54,7 @@ class Emoji(_EmojiTag, AssetMixin):
 
     .. versionchanged:: |vnext|
 
-        This class can now represents app emojis. Use :attr:`Emoji.is_app_emoji` to check for this.
+        This class can now represent app emojis. Use :attr:`Emoji.is_app_emoji` to check for this.
         To check if this is a guild emoji, use :attr:`Emoji.is_guild_emoji`.
 
     Attributes
@@ -74,9 +74,12 @@ class Emoji(_EmojiTag, AssetMixin):
     available: :class:`bool`
         Whether the emoji is available for use.
     user: Optional[:class:`User`]
-        The user that created this emoji. This can only be retrieved using
-        :meth:`Guild.fetch_emoji`/:meth:`Guild.fetch_emojis` while
+        The user that created this emoji. If this is a guild emoji, this can only be retrieved
+        using :meth:`Guild.fetch_emoji`/:meth:`Guild.fetch_emojis` while
         having the :attr:`~Permissions.manage_guild_expressions` permission.
+
+        If this is an app emoji, this is the team member that uploaded the emoji,
+        or the bot user if created using :meth:`Client.create_application_emoji`.
     """
 
     __slots__: Tuple[str, ...] = (
@@ -184,7 +187,8 @@ def guild(self) -> Optional[Guild]:
 
     @property
     def application_id(self) -> Optional[int]:
-        """Optional[:class:`int`]: The ID of the application which owns this emoji.
+        """Optional[:class:`int`]: The ID of the application which owns this emoji,
+        if this is an app emoji.
 
         .. versionadded:: |vnext|
         """
@@ -194,15 +198,15 @@ def application_id(self) -> Optional[int]:
 
     @property
     def is_guild_emoji(self) -> bool:
-        """:class:`bool`: Whether this is a guild emoji.
+        """:class:`bool`: Whether this emoji is a guild emoji.
 
         .. versionadded:: |vnext|
         """
         return self.guild_id is not None
 
     @property
     def is_app_emoji(self) -> bool:
-        """:class:`bool`: Whether this is an application emoji.
+        """:class:`bool`: Whether this emoji is an application emoji.
 
         .. versionadded:: |vnext|
         """
@@ -228,16 +232,18 @@ def is_usable(self) -> bool:
     async def delete(self, *, reason: Optional[str] = None) -> None:
         """|coro|
 
-        Deletes the custom emoji.
+        Deletes the emoji.
 
-        You must have :attr:`~Permissions.manage_guild_expressions` permission to
-        do this.
+        If this is not an app emoji, you must have
+        :attr:`~Permissions.manage_guild_expressions` permission to do this.
 
         Parameters
         ----------
         reason: Optional[:class:`str`]
             The reason for deleting this emoji. Shows up on the audit log.
 
+            Only applies to emojis that belong to a :class:`.Guild`.
+
         Raises
         ------
         Forbidden
@@ -251,7 +257,10 @@ async def delete(self, *, reason: Optional[str] = None) -> None:
         if self.guild is None:
             if self.application_id is None:
                 # should never happen
-                msg = f"guild and application_id are both None when attempting to delete emoji with ID {self.id} This may be a library bug! Open an issue on GitHub."
+                msg = (
+                    f"guild_id and application_id are both None when attempting to delete emoji with ID {self.id}."
+                    " This may be a library bug! Open an issue on GitHub."
+                )
                 raise InvalidData(msg)
 
             return await self._state.http.delete_app_emoji(self.application_id, self.id)
@@ -262,10 +271,10 @@ async def edit(
     ) -> Emoji:
         """|coro|
 
-        Edits the custom emoji.
+        Edits the emoji.
 
-        You must have :attr:`~Permissions.manage_guild_expressions` permission to
-        do this.
+        If this emoji is a guild emoji, you must have
+        :attr:`~Permissions.manage_guild_expressions` permission to do this.
 
         .. versionchanged:: 2.0
             The newly updated emoji is returned.
@@ -280,9 +289,13 @@ async def edit(
             An emoji cannot have both subscription roles (see :attr:`RoleTags.integration_id`) and
             non-subscription roles, and emojis can't be converted between premium and non-premium
             after creation.
+
+            Only applies to emojis that belong to a :class:`.Guild`.
         reason: Optional[:class:`str`]
             The reason for editing this emoji. Shows up on the audit log.
 
+            Only applies to emojis that belong to a :class:`.Guild`.
+
         Raises
         ------
         Forbidden
@@ -306,7 +319,10 @@ async def edit(
         if self.guild is None:
             if self.application_id is None:
                 # should never happen
-                msg = f"guild and application_id are both None when attempting to edit emoji with ID {self.id} This may be a library bug! Open an issue on GitHub."
+                msg = (
+                    f"guild_id and application_id are both None when attempting to edit emoji with ID {self.id}."
+                    " This may be a library bug! Open an issue on GitHub."
+                )
                 raise InvalidData(msg)
 
             data = await self._state.http.edit_app_emoji(self.application_id, self.id, name)