Add XML docs

src/Discord.Net.Core/Entities/Roles/Color.cs

@@ -66,8 +66,15 @@ namespace Discord
         public byte B => (byte)(RawValue);
 
         /// <summary>
-        ///     Initializes a <see cref="Color" /> struct with the given raw value.
+        ///     Initializes a <see cref="Color" /> <see langword="struct"/> with the given raw value.
         /// </summary>
+        /// <example>
+        ///     The following will create a color that has a hex value of 
+        ///     <see href="http://www.color-hex.com/color/607d8b">#607D8B</see>.
+        ///     <code language="cs">
+        ///         Color darkGrey = new Color(0x607D8B);
+        ///     </code>
+        /// </example>
         /// <param name="rawValue">The raw value of the color (e.g. <c>0x607D8B</c>).</param>
         public Color(uint rawValue)
         {
@@ -76,6 +83,13 @@ namespace Discord
         /// <summary>
         ///     Initializes a <see cref="Color" /> struct with the given RGB bytes.
         /// </summary>
+        /// <example>
+        ///     The following will create a color that has a value of 
+        ///     <see href="http://www.color-hex.com/color/607d8b">#607D8B</see>.
+        ///     <code language="cs">
+        ///         Color darkGrey = new Color((byte)0b_01100000, (byte)0b_01111101, (byte)0b_10001011);
+        ///     </code>
+        /// </example>
         /// <param name="r">The byte that represents the red color.</param>
         /// <param name="g">The byte that represents the green color.</param>
         /// <param name="b">The byte that represents the blue color.</param>
@@ -90,6 +104,13 @@ namespace Discord
         /// <summary>
         ///     Initializes a <see cref="Color"/> struct with the given RGB value.
         /// </summary>
+        /// <example>
+        ///     The following will create a color that has a value of 
+        ///     <see href="http://www.color-hex.com/color/607d8b">#607D8B</see>.
+        ///     <code language="cs">
+        ///         Color darkGrey = new Color(96, 125, 139);
+        ///     </code>
+        /// </example>
         /// <param name="r">The value that represents the red color. Must be within 0~255.</param>
         /// <param name="g">The value that represents the green color. Must be within 0~255.</param>
         /// <param name="b">The value that represents the blue color. Must be within 0~255.</param>
@@ -110,6 +131,13 @@ namespace Discord
         /// <summary>
         ///     Initializes a <see cref="Color"/> struct with the given RGB float value.
         /// </summary>
+        /// <example>
+        ///     The following will create a color that has a value of 
+        ///     <see href="http://www.color-hex.com/color/607c8c">#607c8c</see>.
+        ///     <code language="cs">
+        ///         Color darkGrey = new Color(0.38f, 0.49f, 0.55f);
+        ///     </code>
+        /// </example>
         /// <param name="r">The value that represents the red color. Must be within 0~1.</param>
         /// <param name="g">The value that represents the green color. Must be within 0~1.</param>
         /// <param name="b">The value that represents the blue color. Must be within 0~1.</param>

src/Discord.Net.Core/IDiscordClient.cs

@@ -23,7 +23,26 @@ namespace Discord
         /// </summary>
         TokenType TokenType { get; }
 
+        /// <summary>
+        ///     Starts the connection between Discord and the client..
+        /// </summary>
+        /// <remarks>
+        ///     This method will initialize the connection between the client and Discord.
+        ///     <note type="important">
+        ///         This method will immediately return after it is called, as it will initialize the connection on
+        ///         another thread.
+        ///     </note>
+        /// </remarks>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task StartAsync();
+        /// <summary>
+        ///     Stops the connection between Discord and the client.
+        /// </summary>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task StopAsync();
 
         /// <summary>
@@ -40,24 +59,52 @@ namespace Discord
         Task<IApplication> GetApplicationInfoAsync(RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a generic channel with the provided ID.
+        ///     Gets a generic channel via the snowflake identifier.
         /// </summary>
-        /// <param name="id">The ID of the channel.</param>
-        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
+        /// <example>
+        ///     <code lang="cs" title="Example method">
+        ///         var channel = await _client.GetChannelAsync(381889909113225237);
+        ///         if (channel != null &amp;&amp; channel is IMessageChannel msgChannel)
+        ///         {
+        ///             await msgChannel.SendMessageAsync($"{msgChannel} is created at {msgChannel.CreatedAt}");
+        ///         }
+        ///    </code>
+        /// </example>
+        /// <param name="id">The snowflake identifier of the channel (e.g. `381889909113225237`).</param>
+        /// <param name="mode">
+        /// The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.
+        /// </param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing the channel associated with the snowflake identifier.
+        /// </returns>
         Task<IChannel> GetChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets a list of private channels.
+        ///     Gets a collection of private channels opened in this session.
         /// </summary>
         /// <param name="mode">
         /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
         /// </param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <remarks>
+        ///     This method will retrieve all private channels (including direct-message, group channel and such) that
+        ///     are currently opened in this session.
+        ///     <note type="warning">
+        ///         This method will not return previously opened private channels outside of the current session! If
+        ///         you have just started the client, this may return an empty collection.
+        ///     </note>
+        /// </remarks>
+        /// <returns>
+        ///     An awaitable <see cref="Task" /> containing a collection of private channels that have been opened in
+        ///     this session.
+        /// </returns>
         Task<IReadOnlyCollection<IPrivateChannel>> GetPrivateChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Returns a collection of direct message channels.
+        ///     Gets a collection of direct message channels opened in this session.
         /// </summary>
         /// <remarks>
         ///     This method returns a collection of currently opened direct message channels.
-        ///     <note type="note">
+        ///     <note type="warning">
         ///         This method will not return previously opened DM channels outside of the current session! If you
         ///         have just started the client, this may return an empty collection.
         ///     </note>
@@ -65,16 +112,30 @@ namespace Discord
         /// <param name="mode">
         /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
         /// </param>
+        /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task" /> containing a collection of DM channels.
+        ///     An awaitable <see cref="Task" /> containing a collection of DM channels that have been opened in this
+        ///     session.
         /// </returns>
         Task<IReadOnlyCollection<IDMChannel>> GetDMChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets a list of group channels.
+        ///     Gets a collection of group channels opened in this session.
         /// </summary>
+        /// <remarks>
+        ///     This method returns a collection of currently opened group channels.
+        ///     <note type="warning">
+        ///         This method will not return previously opened group channels outside of the current session! If you
+        ///         have just started the client, this may return an empty collection.
+        ///     </note>
+        /// </remarks>
         /// <param name="mode">
         /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
         /// </param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task" /> containing a collection of group channels that have been opened in this
+        ///     session.
+        /// </returns>
         Task<IReadOnlyCollection<IGroupChannel>> GetGroupChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
 
         Task<IReadOnlyCollection<IConnection>> GetConnectionsAsync(RequestOptions options = null);
@@ -85,7 +146,41 @@ namespace Discord
         
         Task<IInvite> GetInviteAsync(string inviteId, bool withCount = false, RequestOptions options = null);
 
+        /// <summary>
+        ///     Gets a user via the snowflake identifier.
+        /// </summary>
+        /// <example>
+        ///     <code lang="cs" title="Example method">
+        ///         var user = await _client.GetUserAsync(168693960628371456);
+        ///         if (user != null)
+        ///             Console.WriteLine($"{user} is created at {user.CreatedAt}.";
+        ///     </code>
+        /// </example>
+        /// <param name="id">The snowflake identifier of the user (e.g. `168693960628371456`).</param>
+        /// <param name="mode">
+        /// The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.
+        /// </param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing the fetched user; <c>null</c> if none is found.
+        /// </returns>
         Task<IUser> GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
+        /// <summary>
+        ///     Gets a user via the username and discriminator combo.
+        /// </summary>
+        /// <example>
+        ///     <code language="cs" title="Example method">
+        ///         var user = await _client.GetUserAsync("Still", "2876");
+        ///         if (user != null)
+        ///             Console.WriteLine($"{user} is created at {user.CreatedAt}.";
+        ///     </code>
+        /// </example>
+        /// <param name="username">The name of the user (e.g. `Still`).</param>
+        /// <param name="discriminator">The discriminator value of the user (e.g. `2876`).</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task" /> containing the fetched user; <c>null</c> if none is found.
+        /// </returns>
         Task<IUser> GetUserAsync(string username, string discriminator, RequestOptions options = null);
 
         Task<IReadOnlyCollection<IVoiceRegion>> GetVoiceRegionsAsync(RequestOptions options = null);
@@ -93,6 +188,14 @@ namespace Discord
 
         Task<IWebhook> GetWebhookAsync(ulong id, RequestOptions options = null);
 
+        /// <summary>
+        ///     Gets the recommended shard count as suggested by Discord.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing an <see cref="int"/> that represents the number of shards
+        ///     that should be used with this account.
+        /// </returns>
         Task<int> GetRecommendedShardCountAsync(RequestOptions options = null);
     }
 }

src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs

@@ -258,10 +258,39 @@ namespace Discord.Rest
             }
             return null;
         }
+        /// <summary>
+        ///     Creates a text channel with the provided name.
+        /// </summary>
+        /// <param name="name">The name of the new channel.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
+        /// <returns>
+        ///     The created text channel.
+        /// </returns>
         public Task<RestTextChannel> CreateTextChannelAsync(string name, Action<TextChannelProperties> func = null, RequestOptions options = null)
             => GuildHelper.CreateTextChannelAsync(this, Discord, name, options, func);
+        /// <summary>
+        ///     Creates a voice channel with the provided name.
+        /// </summary>
+        /// <param name="name">The name of the new channel.</param>
+        /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
+        /// <returns>
+        ///     The created voice channel.
+        /// </returns>
         public Task<RestVoiceChannel> CreateVoiceChannelAsync(string name, Action<VoiceChannelProperties> func = null, RequestOptions options = null)
             => GuildHelper.CreateVoiceChannelAsync(this, Discord, name, options, func);
+        /// <summary>
+        ///     Creates a category channel with the provided name.
+        /// </summary>
+        /// <param name="name">The name of the new channel.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
+        /// <returns>
+        ///     The created category channel.
+        /// </returns>
         public Task<RestCategoryChannel> CreateCategoryChannelAsync(string name, RequestOptions options = null)
             => GuildHelper.CreateCategoryChannelAsync(this, Discord, name, options);
 

src/Discord.Net.WebSocket/BaseSocketClient.cs

@@ -6,6 +6,9 @@ using Discord.Rest;
 
 namespace Discord.WebSocket
 {
+    /// <summary>
+    ///     Represents the base of a WebSocket-based Discord client.
+    /// </summary>
     public abstract partial class BaseSocketClient : BaseDiscordClient, IDiscordClient
     {
         protected readonly DiscordSocketConfig BaseConfig;

src/Discord.Net.WebSocket/DiscordSocketClient.Events.cs

@@ -1,8 +1,9 @@
-using System;
+using System;
 using System.Threading.Tasks;
+using Discord.API;
 
 namespace Discord.WebSocket
-{                                
+{
     public partial class DiscordSocketClient
     {
         //General
@@ -34,5 +35,9 @@ namespace Discord.WebSocket
             remove { _latencyUpdatedEvent.Remove(value); }
         }
         private readonly AsyncEvent<Func<int, int, Task>> _latencyUpdatedEvent = new AsyncEvent<Func<int, int, Task>>();
+
+        internal DiscordSocketClient(DiscordSocketConfig config, DiscordRestApiClient client) : base(config, client)
+        {
+        }
     }
 }

src/Discord.Net.WebSocket/DiscordSocketClient.cs

@@ -19,6 +19,9 @@ using GameModel = Discord.API.Game;
 
 namespace Discord.WebSocket
 {
+    /// <summary>
+    ///     Represents a WebSocket-based Discord client.
+    /// </summary>
     public partial class DiscordSocketClient : BaseSocketClient, IDiscordClient
     {
         private readonly ConcurrentQueue<ulong> _largeGuilds;
@@ -66,16 +69,47 @@ namespace Discord.WebSocket
         public override IReadOnlyCollection<SocketGuild> Guilds => State.Guilds;
         /// <inheritdoc />
         public override IReadOnlyCollection<ISocketPrivateChannel> PrivateChannels => State.PrivateChannels;
+        /// <summary>
+        ///     Gets a collection of direct message channels opened in this session.
+        /// </summary>
+        /// <remarks>
+        ///     This method returns a collection of currently opened direct message channels.
+        ///     <note type="warning">
+        ///         This method will not return previously opened DM channels outside of the current session! If you
+        ///         have just started the client, this may return an empty collection.
+        ///     </note>
+        /// </remarks>
+        /// <returns>
+        ///     An collection of DM channels that have been opened in this session.
+        /// </returns>
         public IReadOnlyCollection<SocketDMChannel> DMChannels
             => State.PrivateChannels.Select(x => x as SocketDMChannel).Where(x => x != null).ToImmutableArray();
+        /// <summary>
+        ///     Gets a collection of group channels opened in this session.
+        /// </summary>
+        /// <remarks>
+        ///     This method returns a collection of currently opened group channels.
+        ///     <note type="warning">
+        ///         This method will not return previously opened group channels outside of the current session! If you
+        ///         have just started the client, this may return an empty collection.
+        ///     </note>
+        /// </remarks>
+        /// <returns>
+        ///     An collection of group channels that have been opened in this session.
+        /// </returns>
         public IReadOnlyCollection<SocketGroupChannel> GroupChannels
             => State.PrivateChannels.Select(x => x as SocketGroupChannel).Where(x => x != null).ToImmutableArray();
         /// <inheritdoc />
         public override IReadOnlyCollection<RestVoiceRegion> VoiceRegions => _voiceRegions.ToReadOnlyCollection();
 
-        /// <summary> Creates a new REST/WebSocket Discord client. </summary>
+        /// <summary>
+        ///     Initializes a new REST/WebSocket-based Discord client.
+        /// </summary>
         public DiscordSocketClient() : this(new DiscordSocketConfig()) { }
-        /// <summary> Creates a new REST/WebSocket Discord client. </summary>
+        /// <summary>
+        ///     Initializes a new REST/WebSocket-based Discord client with the provided configuration.
+        /// </summary>
+        /// <param name="config">The configuration to be used with the client.</param>
         public DiscordSocketClient(DiscordSocketConfig config) : this(config, CreateApiClient(config), null, null) { }
         internal DiscordSocketClient(DiscordSocketConfig config, SemaphoreSlim groupLock, DiscordSocketClient parentClient) : this(config, CreateApiClient(config), groupLock, parentClient) { }
         private DiscordSocketClient(DiscordSocketConfig config, API.DiscordSocketApiClient client, SemaphoreSlim groupLock, DiscordSocketClient parentClient)

src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs

@@ -54,8 +54,8 @@ namespace Discord.WebSocket
         ///     Gets the number of members.
         /// </summary>
         /// <remarks>
-        ///     The number of members is returned by Discord and is the most accurate. You may see discrepancy between
-        ///     the <see cref="Users"/> collection and this.
+        ///     This property retrieves the number of members returned by Discord and is the most accurate. You may see
+        ///     discrepancy between the <see cref="Users"/> collection and this property.
         /// </remarks>
         public int MemberCount { get; internal set; }
         /// <summary> Gets the number of members downloaded to the local guild cache. </summary>
@@ -98,15 +98,19 @@ namespace Discord.WebSocket
         ///     Gets the first viewable text channel.
         /// </summary>
         /// <remarks>
-        ///     This property does not guarantee the user can send message to it.
+        ///     This method gets the first viewable text channel for the logged-in user. This property does not
+        ///     guarantee the user can send message to it.
         /// </remarks>
         public SocketTextChannel DefaultChannel => TextChannels
             .Where(c => CurrentUser.GetPermissions(c).ViewChannel)
             .OrderBy(c => c.Position)
             .FirstOrDefault();
         /// <summary>
-        ///     Gets the AFK voice channel, or <c>null</c> if none is set.
+        ///     Gets the AFK voice channel in this guild.
         /// </summary>
+        /// <returns>
+        ///     A voice channel set within this guild that AFK users get moved to; otherwise <c>null</c> if none is set.
+        /// </returns>
         public SocketVoiceChannel AFKChannel
         {
             get
@@ -116,8 +120,11 @@ namespace Discord.WebSocket
             }
         }
         /// <summary>
-        ///     Gets the embed channel set in the widget settings of this guild, or <c>null</c> if none is set.
+        ///     Gets the embed channel set in the widget settings of this guild.
         /// </summary>
+        /// <returns>
+        ///     A channel set in the widget settings of this guild; otherwise <c>null</c> if none is set.
+        /// </returns>
         public SocketGuildChannel EmbedChannel
         {
             get
@@ -127,8 +134,12 @@ namespace Discord.WebSocket
             }
         }
         /// <summary>
-        ///     Gets the channel where randomized welcome messages are sent, or <c>null</c> if none is set.
+        ///     Gets the channel where randomized welcome messages are sent.
         /// </summary>
+        /// <returns>
+        ///     A channel where randomized welcome messages are sent in this guild; otherwise <c>null</c> if none is
+        ///     set.
+        /// </returns>
         public SocketTextChannel SystemChannel
         {
             get
@@ -140,6 +151,9 @@ namespace Discord.WebSocket
         /// <summary>
         ///     Gets a collection of text channels present in this guild.
         /// </summary>
+        /// <returns>
+        ///     A collection of text channels in this guild.
+        /// </returns>
         public IReadOnlyCollection<SocketTextChannel> TextChannels
             => Channels.Select(x => x as SocketTextChannel).Where(x => x != null).ToImmutableArray();
         /// <summary>
@@ -459,6 +473,7 @@ namespace Discord.WebSocket
         /// </summary>
         /// <param name="name">The name of the new channel.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
         /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
         /// <returns>
         ///     The created text channel.
@@ -469,6 +484,7 @@ namespace Discord.WebSocket
         ///     Creates a voice channel with the provided name.
         /// </summary>
         /// <param name="name">The name of the new channel.</param>
+        /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
         /// <returns>
@@ -521,11 +537,11 @@ namespace Discord.WebSocket
 
         //Roles
         /// <summary>
-        ///     Returns a role with the provided role ID.
+        ///     Gets a role.
         /// </summary>
-        /// <param name="id">The ID of the role.</param>
+        /// <param name="id">The snowflake identifier of the role.</param>
         /// <returns>
-        ///     The role associated with the ID.
+        ///     The role associated with the snowflake identifier.
         /// </returns>
         public SocketRole GetRole(ulong id)
         {
@@ -655,7 +671,7 @@ namespace Discord.WebSocket
         /// <param name="id">The ID of the webhook.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable Task containing the webhook associated with the ID.
+        ///     An awaitable <see cref="Task"/> containing the webhook associated with the ID.
         /// </returns>
         public Task<RestWebhook> GetWebhookAsync(ulong id, RequestOptions options = null)
             => GuildHelper.GetWebhookAsync(this, Discord, id, options);
@@ -664,7 +680,7 @@ namespace Discord.WebSocket
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable Task containing a collection of webhooks.
+        ///     An awaitable <see cref="Task"/> containing a collection of webhooks.
         /// </returns>
         public Task<IReadOnlyCollection<RestWebhook>> GetWebhooksAsync(RequestOptions options = null)
             => GuildHelper.GetWebhooksAsync(this, Discord, options);