[Refactor] Extract GetDisplayAvatarUrl in IUser (#2771)

* Implement `GetDisplayAvatarUrl` method

* Remove obsolete example

* Update XML documentation

---------

Co-authored-by: Quin Lynch <49576606+quinchs@users.noreply.github.com>

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

@@ -133,35 +133,21 @@ public interface IGuildUser : IUser, IVoiceState
         ///     specified channel.
         /// </returns>
         ChannelPermissions GetPermissions(IGuildChannel channel);
-
         /// <summary>
-        ///     Gets the guild avatar URL for this user.
+        ///     Gets the guild-specific avatar URL for this user, if it is set.
         /// </summary>
         /// <remarks>
-        ///     This property retrieves a URL for this guild user's guild specific avatar. In event that the user does not have a valid guild avatar
-        ///     (i.e. their avatar identifier is not set), this method will return <see langword="null"/>.
+        ///     <note type="tip">
+        ///         If you wish to retrieve the display avatar for this user, consider using <see cref="IUser.GetDisplayAvatarUrl"/>.
+        ///     </note>
         /// </remarks>
-        /// <param name="format">The format to return.</param>
-        /// <param name="size">The size of the image to return in. This can be any power of two between 16 and 2048.
-        /// </param>
+        /// <param name="format">The format of the image.</param>
+        /// <param name="size">The size of the image that matches any power of two, ranging from 16 to 2048.</param>
         /// <returns>
-        ///     A string representing the user's avatar URL; <see langword="null"/> if the user does not have an avatar in place.
+        ///     A string representing the user's guild-specific avatar URL; <see langword="null"/> if the user has no guild avatar set.
         /// </returns>
         string GetGuildAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128);
         /// <summary>
-        ///     Gets the display avatar URL for this user.
-        /// </summary>
-        /// <remarks>
-        ///     This property retrieves an URL for this guild user's displayed avatar.
-        ///     If the user does not have a guild avatar, this will be the user's regular avatar.
-        /// </remarks>
-        /// <param name="format">The format to return.</param>
-        /// <param name="size">The size of the image to return in. This can be any power of two between 16 and 2048.</param>
-        /// <returns>
-        ///     A string representing the URL of the displayed avatar for this user. <see langword="null"/> if the user does not have an avatar in place.
-        /// </returns>
-        string GetDisplayAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128);
-        /// <summary>
         ///     Kicks this user from this guild.
         /// </summary>
         /// <param name="reason">The reason for the kick which will be recorded in the audit log.</param>

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

@@ -12,41 +12,45 @@ public interface IUser : ISnowflakeEntity, IMentionable, IPresence
         /// </summary>
         string AvatarId { get; }
         /// <summary>
-        ///     Gets the avatar URL for this user.
+        ///     Gets the avatar URL for this user, if it is set.
         /// </summary>
         /// <remarks>
-        ///     This property retrieves a URL for this user's avatar. In event that the user does not have a valid avatar
-        ///     (i.e. their avatar identifier is not set), this method will return <see langword="null" />. If you wish to
-        ///     retrieve the default avatar for this user, consider using <see cref="IUser.GetDefaultAvatarUrl"/> (see
-        ///     example).
+        ///     <note type="tip">
+        ///         If you wish to retrieve the display avatar for this user, consider using <see cref="GetDisplayAvatarUrl"/>.
+        ///     </note>
         /// </remarks>
-        /// <example>
-        ///     <para
-        ///         >The following example attempts to retrieve the user's current avatar and send it to a channel; if one is
-        ///         not set, a default avatar for this user will be returned instead.</para>
-        ///     <code language="cs" region="GetAvatarUrl"
-        ///           source="..\..\..\Discord.Net.Examples\Core\Entities\Users\IUser.Examples.cs"/>
-        /// </example>
-        /// <param name="format">The format to return.</param>
-        /// <param name="size">The size of the image to return in. This can be any power of two between 16 and 2048.
-        /// </param>
+        /// <param name="format">The format of the image.</param>
+        /// <param name="size">The size of the image that matches any power of two, ranging from 16 to 2048.</param>
         /// <returns>
-        ///     A string representing the user's avatar URL; <see langword="null" /> if the user does not have an avatar in place.
+        ///     A string representing the user's avatar URL; <see langword="null" /> if the user has no avatar set.
         /// </returns>
         string GetAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128);
         /// <summary>
         ///     Gets the default avatar URL for this user.
         /// </summary>
         /// <remarks>
-        ///     This property retrieves a URL for this user's default avatar generated by Discord (Discord logo followed
-        ///     by a random color as its background). This property will always return a value as it is calculated based
-        ///     on the user's <see cref="IUser.DiscriminatorValue"/> (<c>discriminator % 5</c>).
+        ///     This avatar is auto-generated by Discord and consists of their logo combined with a random background color.
+        ///     <note type="note">
+        ///         The calculation is always done by taking the remainder of this user's <see cref="DiscriminatorValue"/> divided by 5.
+        ///     </note>
         /// </remarks>
         /// <returns>
-        ///     A string representing the user's avatar URL.
+        ///     A string representing the user's default avatar URL.
         /// </returns>
         string GetDefaultAvatarUrl();
         /// <summary>
+        ///     Gets the display avatar URL for this user.
+        /// </summary>
+        /// <remarks>
+        ///     This method will return <see cref="GetDefaultAvatarUrl" /> if the user has no avatar set.
+        /// </remarks>
+        /// <param name="format">The format of the image.</param>
+        /// <param name="size">The size of the image that matches any power of two, ranging from 16 to 2048.</param>
+        /// <returns>
+        ///     A string representing the user's display avatar URL.
+        /// </returns>
+        string GetDisplayAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128);
+        /// <summary>
         ///     Gets the per-username unique ID for this user. This will return "0000" for users who have migrated to new username system.
         /// </summary>
         string Discriminator { get; }

src/Discord.Net.Examples/Core/Entities/Users/IUser.Examples.cs

@@ -8,16 +8,6 @@ namespace Discord.Net.Examples.Core.Entities.Users
     [PublicAPI]
     internal class UserExamples
     {
-        #region GetAvatarUrl
-
-        public async Task GetAvatarAsync(IUser user, ITextChannel textChannel)
-        {
-            var userAvatarUrl = user.GetAvatarUrl() ?? user.GetDefaultAvatarUrl();
-            await textChannel.SendMessageAsync(userAvatarUrl);
-        }
-
-        #endregion
-
         #region CreateDMChannelAsync
 
         public async Task MessageUserAsync(IUser user)

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

@@ -194,15 +194,13 @@ public ChannelPermissions GetPermissions(IGuildChannel channel)
             return new ChannelPermissions(Permissions.ResolveChannel(Guild, this, channel, guildPerms.RawValue));
         }
 
-        /// <inheritdoc />
-        public string GetDisplayAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
-            => GuildAvatarId is not null
-                ? GetGuildAvatarUrl(format, size)
-                : GetAvatarUrl(format, size);
-
         /// <inheritdoc />
         public string GetGuildAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
             => CDN.GetGuildUserAvatarUrl(Id, GuildId, GuildAvatarId, size, format);
+
+        /// <inheritdoc />
+        public override string GetDisplayAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
+            => GetGuildAvatarUrl(format, size) ?? base.GetDisplayAvatarUrl(format, size);
         #endregion
 
         #region IGuildUser

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

@@ -142,6 +142,9 @@ public string GetDefaultAvatarUrl()
                 ? CDN.GetDefaultUserAvatarUrl(DiscriminatorValue)
                 : CDN.GetDefaultUserAvatarUrl(Id);
 
+        public virtual string GetDisplayAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
+            => GetAvatarUrl(format, size) ?? GetDefaultAvatarUrl(); 
+
         /// <inheritdoc />
         public string GetAvatarDecorationUrl()
             => AvatarDecorationHash is not null

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

@@ -60,8 +60,6 @@ IGuild IGuildUser.Guild
         /// <inheritdoc />
         string IGuildUser.GuildAvatarId => null;
         /// <inheritdoc />
-        string IGuildUser.GetDisplayAvatarUrl(ImageFormat format, ushort size) => null;
-        /// <inheritdoc />
         string IGuildUser.GetGuildAvatarUrl(ImageFormat format, ushort size) => null;
         /// <inheritdoc />
         bool? IGuildUser.IsPending => null;

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

@@ -259,16 +259,14 @@ public Task RemoveTimeOutAsync(RequestOptions options = null)
         public ChannelPermissions GetPermissions(IGuildChannel channel)
             => new ChannelPermissions(Permissions.ResolveChannel(Guild, this, channel, GuildPermissions.RawValue));
 
-        /// <inheritdoc />
-        public string GetDisplayAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
-            => GuildAvatarId is not null
-                ? GetGuildAvatarUrl(format, size)
-                : GetAvatarUrl(format, size);
-
         /// <inheritdoc />
         public string GetGuildAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
             => CDN.GetGuildUserAvatarUrl(Id, Guild.Id, GuildAvatarId, size, format);
 
+        /// <inheritdoc />
+        public override string GetDisplayAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
+            => GetGuildAvatarUrl(format, size) ?? base.GetDisplayAvatarUrl(format, size);
+
         private string DebuggerDisplay => DiscriminatorValue != 0
             ? $"{Username}#{Discriminator} ({Id}{(IsBot ? ", Bot" : "")}, Guild)"
             : $"{Username} ({Id}{(IsBot ? ", Bot" : "")}, Guild)";

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

@@ -238,10 +238,11 @@ internal void Update(Model model)
         IReadOnlyCollection<ulong> IGuildUser.RoleIds => GuildUser.Roles.Select(x => x.Id).ToImmutableArray();
 
         /// <inheritdoc />
-        string IGuildUser.GetDisplayAvatarUrl(ImageFormat format, ushort size) => GuildUser.GetDisplayAvatarUrl(format, size);
+        string IGuildUser.GetGuildAvatarUrl(ImageFormat format, ushort size) => GuildUser.GetGuildAvatarUrl(format, size);
 
         /// <inheritdoc />
-        string IGuildUser.GetGuildAvatarUrl(ImageFormat format, ushort size) => GuildUser.GetGuildAvatarUrl(format, size);
+        public override string GetDisplayAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
+            => GuildUser.GetGuildAvatarUrl() ?? base.GetDisplayAvatarUrl(format, size);
 
         internal override SocketGlobalUser GlobalUser { get => GuildUser.GlobalUser; set => GuildUser.GlobalUser = value; }
 

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

@@ -137,6 +137,9 @@ public string GetDefaultAvatarUrl()
                 : CDN.GetDefaultUserAvatarUrl(Id);
 
         /// <inheritdoc />
+        public virtual string GetDisplayAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
+            => GetAvatarUrl(format, size) ?? GetDefaultAvatarUrl();
+
         public string GetAvatarDecorationUrl()
             => AvatarDecorationHash is not null
                 ? CDN.GetAvatarDecorationUrl(AvatarDecorationHash)

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

@@ -75,8 +75,6 @@ internal static SocketWebhookUser Create(SocketGuild guild, ClientState state, M
         /// <inheritdoc />
         string IGuildUser.GuildAvatarId => null;
         /// <inheritdoc />
-        string IGuildUser.GetDisplayAvatarUrl(ImageFormat format, ushort size) => null;
-        /// <inheritdoc />
         string IGuildUser.GetGuildAvatarUrl(ImageFormat format, ushort size) => null;
         /// <inheritdoc />
         DateTimeOffset? IGuildUser.PremiumSince => null;