Add IGuildUser.Hirearchy, added docstrings

Property can be renamed as needed.

src/Discord.Net.Core/Entities/Users/IGuildUser.cs

@@ -28,5 +28,10 @@ namespace Discord
         Task KickAsync(RequestOptions options = null);
         /// <summary> Modifies this user's properties in this guild. </summary>
         Task ModifyAsync(Action<ModifyGuildMemberParams> func, RequestOptions options = null);
+
+        /// <summary> The position of the user within the role hirearchy. </summary>
+        /// <remarks> The returned value equal to the position of the highest role the user has, 
+        /// or int.MaxValue if user is the server owner. </remarks>
+        int Hirearchy { get; }
     }
 }

src/Discord.Net.Core/Extensions/GuildUserExtensions.cs

@@ -21,15 +21,20 @@ namespace Discord
             return user.RoleIds.Select(r => guild.GetRole(r));
         }
 
-        public static int CompareRoles(this IGuildUser left, IGuildUser right) {
+        internal static int GetHirearchy(this IGuildUser user) {
-            // These should never be empty since the everyone role is always present
+            if(user == null)
-            var roleLeft = left.GetRoles().Max();
+                return -1;
-            var roleRight= right.GetRoles().Max();
+            if(user.Id == user.Guild.OwnerId)
-            return roleLeft.CompareTo(roleRight);
+                return int.MaxValue;
+            return user.GetRoles().Max(r => r.Position);
         }
 
-        public static int Compare(this IGuildUser user, IRole role) {
+        internal static int CompareRole(this IGuildUser user, IRole role) {
-            return user.GetRoles().Max().CompareTo(role);
+            if(user == null)
+                return -1;
+            if(role == null)
+                return 1;
+            return -user.Hirearchy.CompareTo(role.Position);
         }
     }
 }

src/Discord.Net.Rest/Entities/Users/RestGuildUser.cs

@@ -96,8 +96,8 @@ namespace Discord.Rest
                 throw new InvalidOperationException("Unable to return this entity's parent unless it was fetched through that object.");
             }
         }
-    
+        public int Hirearchy => this.GetHirearchy();
-        public int CompareTo(IRole role) => this.Compare(role);
+        public int CompareTo(IRole role) => this.CompareRole(role);
 
         //IVoiceState
         bool IVoiceState.IsSelfDeafened => false;

src/Discord.Net.WebSocket/Entities/Users/SocketGuildUser.cs

@@ -96,7 +96,8 @@ namespace Discord.WebSocket
         IGuild IGuildUser.Guild => Guild;
         ulong IGuildUser.GuildId => Guild.Id;
         IReadOnlyCollection<ulong> IGuildUser.RoleIds => RoleIds;
-        public int CompareTo(IRole role) => this.Compare(role);
+        public int CompareTo(IRole role) => this.CompareRole(role);
+        public int Hirearchy => this.GetHirearchy();
 
         //IUser
         Task<IDMChannel> IUser.GetDMChannelAsync(CacheMode mode, RequestOptions options)