docs: Improve RoleType and related docs somewhat (#3169)

Co-authored-by: plun1331 <plun1331@gmail.com>

Author: Paillat-dev

discord/enums.py

@@ -1139,7 +1139,7 @@ class SelectDefaultValueType(Enum):
 class RoleType(IntEnum):
     """Represents the type of role.
 
-    This is NOT provided by Discord but is rather computed based on :attr:`Role.tags`.
+    This is NOT provided by Discord but is rather computed from :attr:`Role.tags`.
 
     .. versionadded:: 2.8
 
@@ -1156,7 +1156,8 @@ class RoleType(IntEnum):
 
         .. note::
             This is not possible to determine at times because role tags seem to be missing altogether, notably when
-            a role is fetched. In such cases :attr:`Role.type` and :attr:`Role.tags` will both be :data:`None`.
+            a guild product role is fetched.
+            In such cases :attr:`Role.type` will be :attr:`RoleType.NORMAL` and :attr:`Role.tags` will be :data:`None`.
     PREMIUM_SUBSCRIPTION_BASE: :class:`int`
         The role is a base subscription role.
 

discord/role.py

@@ -213,41 +213,49 @@ def type(self) -> RoleType:
         return RoleType.UNKNOWN
 
     @deprecated(
-        "RoleTags.is_bot_managed is deprecated since version 2.8, consider using RoleTags.type instead."
+        "RoleTags.is_bot_managed is deprecated since version 2.8,"
+        + " consider using RoleTags.type == RoleType.APPLICATION instead."
     )
     def is_bot_managed(self) -> bool:
         """Whether the role is associated with a bot.
 
         .. deprecated:: 2.8
-            Use :attr:`RoleTags.type` instead.
+            Use ``RoleTags.type == RoleType.APPLICATION`` instead.
         """
         return self.bot_id is not None
 
     @deprecated(
-        "RoleTags.is_premium_subscriber is deprecated since version 2.8, consider using RoleTags.type instead."
+        "RoleTags.is_premium_subscriber is deprecated since version 2.8,"
+        + " consider using RoleTags.type == RoleType.BOOSTER instead."
     )
     def is_premium_subscriber(self) -> bool:
         """Whether the role is the premium subscriber, AKA "boost", role for the guild.
 
         .. deprecated:: 2.8
-            Use :attr:`RoleTags.type` instead.
+            Use ``RoleTags.type == RoleType.BOOSTER`` instead.
         """
         return self._premium_subscriber is True
 
     @deprecated(
-        "RoleTags.is_integration is deprecated since version 2.8, consider using RoleTags.type instead."
+        "RoleTags.is_integration is deprecated since version 2.8,"
+        + " consider using RoleTags.type in"
+        + " (RoleType.INTEGRATION, RoleType.PREMIUM_SUBSCRIPTION_TIER,"
+        + " RoleType.DRAFT_PREMIUM_SUBSCRIPTION_TIER) instead."
     )
     def is_integration(self) -> bool:
         """Whether the guild manages the role through some form of
         integrations such as Twitch or through guild subscriptions.
 
         .. deprecated:: 2.8
-            Use :attr:`RoleTags.type` instead.
+            Use ``RoleTags.type in (RoleType.INTEGRATION,
+            RoleType.PREMIUM_SUBSCRIPTION_TIER,
+            RoleType.DRAFT_PREMIUM_SUBSCRIPTION_TIER)`` instead.
         """
         return self.integration_id is not None
 
     @deprecated(
-        "RoleTags.is_available_for_purchase is deprecated since version 2.8, consider using RoleTags.type instead."
+        "RoleTags.is_available_for_purchase is deprecated since version 2.8,"
+        + " consider using RoleTags.type == RoleType.PREMIUM_SUBSCRIPTION_TIER instead."
     )
     def is_available_for_purchase(self) -> bool:
         """Whether the role is available for purchase.
@@ -257,20 +265,21 @@ def is_available_for_purchase(self) -> bool:
         is not linked to a guild subscription.
 
         .. deprecated:: 2.8
-            Use :attr:`RoleTags.type` instead.
+            Use ``RoleTags.type == RoleType.PREMIUM_SUBSCRIPTION_TIER`` instead.
 
         .. versionadded:: 2.7
         """
         return self._available_for_purchase is True
 
     @deprecated(
-        "RoleTags.is_guild_connections_role is deprecated since version 2.8, consider using RoleTags.type instead."
+        "RoleTags.is_guild_connections_role is deprecated since version 2.8,"
+        + " consider using RoleTags.type == RoleType.CONNECTION instead."
     )
     def is_guild_connections_role(self) -> bool:
         """Whether the role is a guild connections role.
 
         .. deprecated:: 2.8
-            Use :attr:`RoleTags.type` instead.
+            Use ``RoleTags.type == RoleType.CONNECTION`` instead.
 
         .. versionadded:: 2.7
         """