Add warning for comparing with role positioning

1 files changed, 9 insertions, 0 deletions

diff --git a/discord/role.py b/discord/role.py
index 22778f8e..a8ce4cea 100644
--- a/discord/role.py
+++ b/discord/role.py
@@ -139,6 +139,15 @@ class Role(Hashable):
     position: :class:`int`
         The position of the role. This number is usually positive. The bottom
         role has a position of 0.
+
+        .. warning::
+
+            Multiple roles can have the same position number. As a consequence
+            of this, comparing via role position is prone to subtle bugs if
+            checking for role hierarchy. The recommended and correct way to
+            compare for roles in the hierarchy is using the comparison
+            operators on the role objects themselves.
+
     managed: :class:`bool`
         Indicates if the role is managed by the guild through some form of
         integrations such as Twitch.