diff --git a/docs/docfx.json b/docs/docfx.json index 46c6ad984..901357ae3 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -61,6 +61,7 @@ "_appFooter": "Discord.Net (c) 2015-2018", "_enableSearch": true }, - "noLangKeyword": false + "noLangKeyword": false, + "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ] } } diff --git a/docs/guides/commands/commands.md b/docs/guides/commands/commands.md index 73dc46d92..4999e2b9d 100644 --- a/docs/guides/commands/commands.md +++ b/docs/guides/commands/commands.md @@ -1,15 +1,15 @@ # The Command Service -[Discord.Commands](xref:Discord.Commands) provides an Attribute-based +[Discord.Commands](xref:Discord.Commands) provides an attribute-based command parser. ## Setup -To use Commands, you must create a [Command Service] and a Command +To use Commands, you must create a [Command Service] and a command Handler. -Included below is a very barebone Command Handler. You can extend your -Command Handler as much as you like; however, the below is the bare +Included below is a very barebone command handler. You can extend your +command Handler as much as you like; however, the below is the bare minimum. The `CommandService` will optionally accept a [CommandServiceConfig], @@ -24,8 +24,8 @@ values. ## With Attributes -In 1.0, Commands can be defined ahead of time with attributes, or at -runtime with builders. +Starting from 1.0, Commands can be defined ahead of time with +attributes, or at runtime with builders. For most bots, ahead-of-time Commands should be all you need, and this is the recommended method of defining Commands. @@ -39,23 +39,24 @@ Commands in different classes and have them automatically loaded. Discord.Net's implementation of Modules is influenced heavily from ASP.NET Core's Controller pattern. This means that the lifetime of a -module instance is only as long as the Command is being invoked. +module instance is only as long as the command is being invoked. -**Avoid using long-running code** in your modules wherever possible. -You should **not** be implementing very much logic into your modules, -instead, outsource to a service for that. - -If you are unfamiliar with Inversion of Control, it is recommended to -read the MSDN article on [IoC] and [Dependency Injection]. - -To begin, create a new class somewhere in your project and inherit the -class from [ModuleBase]. This class **must** be `public`. +> [!WARNING] +> **Avoid using long-running code** in your modules wherever possible. +> You should **not** be implementing very much logic into your +> modules, instead, outsource to a service for that. +> +> If you are unfamiliar with Inversion of Control, it is recommended +> to read the MSDN article on [IoC] and [Dependency Injection]. >[!NOTE] >[ModuleBase] is an _abstract_ class, meaning that you may extend it >or override it as you see fit. Your module may inherit from any >extension of ModuleBase. +To begin, create a new class somewhere in your project and inherit the +class from [ModuleBase]. This class **must** be `public`. + By now, your module should look like this: [!code-csharp[Empty Module](samples/empty-module.cs)] @@ -66,36 +67,36 @@ By now, your module should look like this: ### Adding Commands -The next step to creating Commands is actually creating the Commands. +The next step to creating commands is actually creating the commands. -To create a Command, add a method to your module of type `Task`. +To create a command, add a method to your module of type `Task` or +`Task` depending on your use. Typically, you will want to mark this method as `async`, although it is not required. -Adding parameters to a Command is done by adding parameters to the -parent Task. - -For example, to take an integer as an argument from the user, add `int -arg`; to take a user as an argument from the user, add `IUser user`. -In 1.0, a Command can accept nearly any type of argument; a full list -of types that are parsed by default can be found in the below section -on _Type Readers_. +Adding parameters to a command is done by adding parameters to the +parent Task. For example, to take an integer as an argument from +the user, add `int arg`; to take a user as an argument from the +user, add `IUser user`. Starting from 1.0, a command can accept +nearly any type of argument; a full list of types that are parsed +by default can be found in the below +section on [Type Readers](#type-readers). Parameters, by default, are always required. To make a parameter optional, give it a default value. To accept a comma-separated list, set the parameter to `params Type[]`. -Should a parameter include spaces, it **must** be wrapped in quotes. -For example, for a Command with a parameter `string food`, you would -execute it with `!favoritefood "Key Lime Pie"`. - -If you would like a parameter to parse until the end of a Command, -flag the parameter with the [RemainderAttribute]. This will allow a -user to invoke a Command without wrapping a parameter in quotes. +Should a parameter include spaces, the parameter **must** be +wrapped in quotes. For example, for a command with a parameter +`string food`, you would execute it with +`!favoritefood "Key Lime Pie"`. If you would like a parameter to +parse until the end of a command, flag the parameter with the +[RemainderAttribute]. This will allow a user to invoke a command +without wrapping a parameter in quotes. -Finally, flag your Command with the [CommandAttribute]. (you must -specify a name for this Command, except for when it is part of a -Module Group - see below) +Finally, flag your command with the [CommandAttribute] (you must +specify a name for this command, except for when it is part of a +[Module Group](#module-groups). [RemainderAttribute]: xref:Discord.Commands.RemainderAttribute [CommandAttribute]: xref:Discord.Commands.CommandAttribute @@ -114,11 +115,10 @@ priority will be called first. ### Command Context -Every Command can access the execution context through the [Context] +Every command can access the execution context through the [Context] property on [ModuleBase]. `ICommandContext` allows you to access the -message, channel, guild, and user that the Command was invoked from, -as well as the underlying Discord client that the Command was invoked -from. +message, channel, guild, user, and the underlying Discord client +that the command was invoked from. Different types of Contexts may be specified using the generic variant of [ModuleBase]. When using a [SocketCommandContext], for example, the @@ -132,7 +132,7 @@ accessing the channel through the [Context] and sending a message. >Contexts should **NOT** be mixed! You cannot have one module that >uses `CommandContext` and another that uses `SocketCommandContext`. -[Context]: xref:Discord.Commands.ModuleBase`1#Discord_Commands_ModuleBase_1_Context +[Context]: xref:Discord.Commands.ModuleBase`1.Context [SocketCommandContext]: xref:Discord.Commands.SocketCommandContext [ReplyAsync]: xref:Discord.Commands.ModuleBase`1.ReplyAsync* @@ -144,14 +144,13 @@ At this point, your module should look comparable to this example: #### Loading Modules Automatically The Command Service can automatically discover all classes in an -Assembly that inherit [ModuleBase] and load them. +Assembly that inherit [ModuleBase] and load them. Invoke +[CommandService.AddModulesAsync] to discover modules and +install them. To opt a module out of auto-loading, flag it with [DontAutoLoadAttribute]. -Invoke [CommandService.AddModulesAsync] to discover modules and -install them. - [DontAutoLoadAttribute]: xref:Discord.Commands.DontAutoLoadAttribute [CommandService.AddModulesAsync]: xref:Discord.Commands.CommandService.AddModulesAsync* @@ -187,7 +186,7 @@ prefixed. To create a group, flag a module with the Module groups also allow you to create **nameless Commands**, where the [CommandAttribute] is configured with no name. In this case, the -Command will inherit the name of the group it belongs to. +command will inherit the name of the group it belongs to. ### Submodules @@ -209,20 +208,19 @@ DI when writing your modules. ### Setup -First, you need to create an @System.IServiceProvider; you may create -your own one if you wish. +First, you need to create an @System.IServiceProvider. -Next, add the dependencies that your modules will use to the map. +Next, add the dependencies to the service collection that you wish +to use in the Modules. -Finally, pass the map into the `LoadAssembly` method. Your modules -will be automatically loaded with this dependency map. +Finally, pass the service collection into `AddModulesAsync`. [!code-csharp[IServiceProvider Setup](samples/dependency_map_setup.cs)] ### Usage in Modules In the constructor of your Module, any parameters will be filled in by -the @System.IServiceProvider that you've passed into `LoadAssembly`. +the @System.IServiceProvider that you've passed. Any publicly settable properties will also be filled in the same manner. @@ -264,6 +262,7 @@ usages on their respective API pages. - @Discord.Commands.RequireOwnerAttribute - @Discord.Commands.RequireBotPermissionAttribute - @Discord.Commands.RequireUserPermissionAttribute +- @Discord.Commands.RequireNsfwAttribute ## Custom Preconditions diff --git a/docs/guides/commands/samples/command_handler.cs b/docs/guides/commands/samples/command_handler.cs index da2453aa8..1e68d70ec 100644 --- a/docs/guides/commands/samples/command_handler.cs +++ b/docs/guides/commands/samples/command_handler.cs @@ -40,7 +40,7 @@ public class Program // Hook the MessageReceived Event into our Command Handler _client.MessageReceived += HandleCommandAsync; // Discover all of the commands in this assembly and load them. - await _commands.AddModulesAsync(Assembly.GetEntryAssembly()); + await _commands.AddModulesAsync(Assembly.GetEntryAssembly(), _services); } private async Task HandleCommandAsync(SocketMessage messageParam) diff --git a/docs/guides/commands/samples/dependency_map_setup.cs b/docs/guides/commands/samples/dependency_map_setup.cs index a36925904..34e4c994e 100644 --- a/docs/guides/commands/samples/dependency_map_setup.cs +++ b/docs/guides/commands/samples/dependency_map_setup.cs @@ -14,5 +14,5 @@ public async Task InstallAsync(DiscordSocketClient client) .AddSingleton() .BuildServiceProvider(); // ... - await _commands.AddModulesAsync(Assembly.GetEntryAssembly()); + await _commands.AddModulesAsync(Assembly.GetEntryAssembly(), _services); } \ No newline at end of file diff --git a/docs/guides/commands/samples/dependency_module.cs b/docs/guides/commands/samples/dependency_module.cs index 561b0f6ac..24009cc41 100644 --- a/docs/guides/commands/samples/dependency_module.cs +++ b/docs/guides/commands/samples/dependency_module.cs @@ -2,7 +2,7 @@ using Discord; using Discord.Commands; using Discord.WebSocket; -public class ModuleA : ModuleBase +public class ModuleA : ModuleBase { private readonly DatabaseService _database; @@ -19,11 +19,11 @@ public class ModuleA : ModuleBase } } -public class ModuleB +public class ModuleB : ModuleBase { // Public settable properties will be injected - public AnnounceService { get; set; } + public AnnounceService Announce { get; set; } // Public properties without setters will not public CommandService Commands { get; } diff --git a/docs/guides/commands/samples/module.cs b/docs/guides/commands/samples/module.cs index 1e3555501..ad96b6051 100644 --- a/docs/guides/commands/samples/module.cs +++ b/docs/guides/commands/samples/module.cs @@ -1,14 +1,13 @@ // Create a module with no prefix public class Info : ModuleBase { - // ~say hello -> hello + // ~say hello world -> hello world [Command("say")] [Summary("Echoes a message.")] - public async Task SayAsync([Remainder] [Summary("The text to echo")] string echo) - { - // ReplyAsync is a method on ModuleBase - await ReplyAsync(echo); - } + public Task SayAsync([Remainder] [Summary("The text to echo")] string echo) + => ReplyAsync(echo); + + // ReplyAsync is a method on ModuleBase } // Create a module with the 'sample' prefix @@ -18,7 +17,9 @@ public class Sample : ModuleBase // ~sample square 20 -> 400 [Command("square")] [Summary("Squares a number.")] - public async Task SquareAsync([Summary("The number to square.")] int num) + public async Task SquareAsync( + [Summary("The number to square.")] + int num) { // We can also access the channel from the Command Context. await Context.Channel.SendMessageAsync($"{num}^2 = {Math.Pow(num, 2)}"); @@ -31,9 +32,12 @@ public class Sample : ModuleBase // ~sample userinfo 96642168176807936 --> Khionu#8708 // ~sample whois 96642168176807936 --> Khionu#8708 [Command("userinfo")] - [Summary("Returns info about the current user, or the user parameter, if one passed.")] + [Summary + ("Returns info about the current user, or the user parameter, if one passed.")] [Alias("user", "whois")] - public async Task UserInfoAsync([Summary("The (optional) user to get info for")] SocketUser user = null) + public async Task UserInfoAsync( + [Summary("The (optional) user to get info for")] + SocketUser user = null) { var userInfo = user ?? Context.Client.CurrentUser; await ReplyAsync($"{userInfo.Username}#{userInfo.Discriminator}"); diff --git a/docs/guides/commands/samples/require_owner.cs b/docs/guides/commands/samples/require_owner.cs index 3611afab8..aa218539e 100644 --- a/docs/guides/commands/samples/require_owner.cs +++ b/docs/guides/commands/samples/require_owner.cs @@ -10,7 +10,7 @@ using System.Threading.Tasks; public class RequireOwnerAttribute : PreconditionAttribute { // Override the CheckPermissions method - public async override Task CheckPermissions(ICommandContext context, CommandInfo command, IServiceProvider services) + public async override Task CheckPermissionsAsync(ICommandContext context, CommandInfo command, IServiceProvider services) { // Get the ID of the bot's owner var ownerId = (await services.GetService().GetApplicationInfoAsync()).Owner.Id; diff --git a/docs/guides/commands/samples/typereader.cs b/docs/guides/commands/samples/typereader.cs index d2864a4c7..b792a9269 100644 --- a/docs/guides/commands/samples/typereader.cs +++ b/docs/guides/commands/samples/typereader.cs @@ -4,7 +4,7 @@ using Discord.Commands; public class BooleanTypeReader : TypeReader { - public override Task Read(ICommandContext context, string input, IServiceProvider services) + public override Task ReadAsync(ICommandContext context, string input, IServiceProvider services) { bool result; if (bool.TryParse(input, out result)) diff --git a/src/Discord.Net.Commands/Attributes/CommandAttribute.cs b/src/Discord.Net.Commands/Attributes/CommandAttribute.cs index e1fc59a73..eeb43bad3 100644 --- a/src/Discord.Net.Commands/Attributes/CommandAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/CommandAttribute.cs @@ -7,7 +7,7 @@ namespace Discord.Commands public class CommandAttribute : Attribute { /// - /// Specifies the text required to be recognized as a command. + /// Gets the text that has been set to be recognized as a command. /// public string Text { get; } /// diff --git a/src/Discord.Net.Commands/Attributes/DontAutoLoadAttribute.cs b/src/Discord.Net.Commands/Attributes/DontAutoLoadAttribute.cs index cc23a6d15..22664afd1 100644 --- a/src/Discord.Net.Commands/Attributes/DontAutoLoadAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/DontAutoLoadAttribute.cs @@ -2,6 +2,7 @@ using System; namespace Discord.Commands { + /// Prevents the module from being loaded automatically. [AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true)] public class DontAutoLoadAttribute : Attribute { diff --git a/src/Discord.Net.Commands/Attributes/DontInjectAttribute.cs b/src/Discord.Net.Commands/Attributes/DontInjectAttribute.cs index c982d93a1..354b87364 100644 --- a/src/Discord.Net.Commands/Attributes/DontInjectAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/DontInjectAttribute.cs @@ -2,6 +2,7 @@ using System; namespace Discord.Commands { + /// Prevents the property from being injected into a module. [AttributeUsage(AttributeTargets.Property, AllowMultiple = false, Inherited = true)] public class DontInjectAttribute : Attribute { } diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireBotPermissionAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireBotPermissionAttribute.cs index 1afe82685..152376819 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireBotPermissionAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireBotPermissionAttribute.cs @@ -4,7 +4,7 @@ using System.Threading.Tasks; namespace Discord.Commands { /// - /// This attribute requires the bot to have a specific permission in the channel a command is invoked in. + /// Requires the bot to have a specific permission in the channel a command is invoked in. /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireBotPermissionAttribute : PreconditionAttribute @@ -13,7 +13,7 @@ namespace Discord.Commands public ChannelPermission? ChannelPermission { get; } /// - /// Requires that the bot account to have a specific . + /// Requires the bot account to have a specific . /// /// This precondition will always fail if the command is being invoked in a private channel. /// The GuildPermission that the bot must have. Multiple permissions can be specified by ORing the permissions together. diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs index 252d8b5f2..bf5d081ce 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs @@ -13,7 +13,7 @@ namespace Discord.Commands } /// - /// This attribute requires that the command be invoked in a specified context. (e.g. in guild, DM) + /// Requires the command to be invoked in a specified context. (e.g. in guild, DM) /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireContextAttribute : PreconditionAttribute diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs index baff01d8c..ec3931dbe 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs @@ -4,7 +4,7 @@ using System.Threading.Tasks; namespace Discord.Commands { /// - /// This attribute requires that the command to be invoked in a channel marked NSFW. + /// Requires the command to be invoked in a channel marked NSFW. /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireNsfwAttribute : PreconditionAttribute diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs index bf6a3352e..bade39bc2 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs @@ -4,7 +4,7 @@ using System.Threading.Tasks; namespace Discord.Commands { /// - /// This attribute requires that the command to be invoked by the owner of the bot. + /// Requires the command to be invoked by the owner of the bot. /// /// This precondition will only work if the bot is a bot account. [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs index 7aaeab064..6343ca190 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs @@ -4,7 +4,7 @@ using System.Threading.Tasks; namespace Discord.Commands { /// - /// This attribute requires that the user invoking the command has a specified permission. + /// Requires the user invoking the command to have a specified permission. /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireUserPermissionAttribute : PreconditionAttribute diff --git a/src/Discord.Net.Commands/Attributes/PriorityAttribute.cs b/src/Discord.Net.Commands/Attributes/PriorityAttribute.cs index 353e96e41..ad49ebb06 100644 --- a/src/Discord.Net.Commands/Attributes/PriorityAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/PriorityAttribute.cs @@ -2,11 +2,11 @@ using System; namespace Discord.Commands { - /// Sets priority of commands + /// Sets priority of commands. [AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = true)] public class PriorityAttribute : Attribute { - /// The priority which has been set for the command + /// Gets the priority which has been set for the command. public int Priority { get; } /// Creates a new with the given priority. diff --git a/src/Discord.Net.Core/ConnectionState.cs b/src/Discord.Net.Core/ConnectionState.cs index 42c505ccd..b240eb134 100644 --- a/src/Discord.Net.Core/ConnectionState.cs +++ b/src/Discord.Net.Core/ConnectionState.cs @@ -1,10 +1,15 @@ -namespace Discord +namespace Discord { + /// Specifies the connection state of a client. public enum ConnectionState : byte { + /// Represents that the client has disconnected from the WebSocket. Disconnected, + /// Represents that the client is connecting to the WebSocket. Connecting, + /// Represents that the client has established a connection to the WebSocket. Connected, + /// Represents that the client is disconnecting from the WebSocket. Disconnecting } } diff --git a/src/Discord.Net.Core/Entities/Activities/ActivityType.cs b/src/Discord.Net.Core/Entities/Activities/ActivityType.cs index 4cc71b119..14281a329 100644 --- a/src/Discord.Net.Core/Entities/Activities/ActivityType.cs +++ b/src/Discord.Net.Core/Entities/Activities/ActivityType.cs @@ -1,17 +1,15 @@ namespace Discord { - /// - /// Defines user's activity type. - /// + /// Specifies a Discord user's activity type. public enum ActivityType { - /// Activity that represents a user that is playing a game. + /// Represents that the user is playing a game. Playing = 0, - /// Activity that represents a user that is streaming online. + /// Represents that the user is streaming online. Streaming = 1, - /// Activity that represents a user that is listening to a song. + /// Represents that the user is listening to a song. Listening = 2, - /// Activity that represents a user that is watching a media. + /// Represents that the user is watching a media. Watching = 3 } } diff --git a/src/Discord.Net.Core/Entities/Activities/Game.cs b/src/Discord.Net.Core/Entities/Activities/Game.cs index 179ad4eaa..5c5bd98b5 100644 --- a/src/Discord.Net.Core/Entities/Activities/Game.cs +++ b/src/Discord.Net.Core/Entities/Activities/Game.cs @@ -2,10 +2,13 @@ using System.Diagnostics; namespace Discord { + /// A user's game activity. [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class Game : IActivity { + /// public string Name { get; internal set; } + /// public ActivityType Type { get; internal set; } internal Game() { } diff --git a/src/Discord.Net.Core/Entities/Activities/GameAsset.cs b/src/Discord.Net.Core/Entities/Activities/GameAsset.cs index ee084235d..78560ebe3 100644 --- a/src/Discord.Net.Core/Entities/Activities/GameAsset.cs +++ b/src/Discord.Net.Core/Entities/Activities/GameAsset.cs @@ -1,6 +1,6 @@ namespace Discord { - /// The asset for a object. + /// An asset for a object. public class GameAsset { internal GameAsset() { } diff --git a/src/Discord.Net.Core/Entities/Activities/GameTimestamps.cs b/src/Discord.Net.Core/Entities/Activities/GameTimestamps.cs index 846832796..572547d6e 100644 --- a/src/Discord.Net.Core/Entities/Activities/GameTimestamps.cs +++ b/src/Discord.Net.Core/Entities/Activities/GameTimestamps.cs @@ -2,7 +2,7 @@ using System; namespace Discord { - /// The timestamps for a object. + /// Timestamps for a object. public class GameTimestamps { public DateTimeOffset? Start { get; } diff --git a/src/Discord.Net.Core/Entities/Activities/IActivity.cs b/src/Discord.Net.Core/Entities/Activities/IActivity.cs index 1f158217d..1b2ebc540 100644 --- a/src/Discord.Net.Core/Entities/Activities/IActivity.cs +++ b/src/Discord.Net.Core/Entities/Activities/IActivity.cs @@ -1,8 +1,11 @@ -namespace Discord +namespace Discord { + /// A Discord activity. public interface IActivity { + /// Gets the name of the activity. string Name { get; } + /// Gets the type of the activity. ActivityType Type { get; } } } diff --git a/src/Discord.Net.Core/Entities/Activities/SpotifyGame.cs b/src/Discord.Net.Core/Entities/Activities/SpotifyGame.cs index a20384242..1db816037 100644 --- a/src/Discord.Net.Core/Entities/Activities/SpotifyGame.cs +++ b/src/Discord.Net.Core/Entities/Activities/SpotifyGame.cs @@ -4,19 +4,28 @@ using System.Diagnostics; namespace Discord { + /// A user's activity for listening to a song on Spotify. [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class SpotifyGame : Game { + /// Gets the song's artist(s). public IEnumerable Artists { get; internal set; } + /// Gets the Spotify album art for the song. public string AlbumArt { get; internal set; } + /// Gets the Spotify album title for the song. public string AlbumTitle { get; internal set; } + /// Gets the track title for the song. public string TrackTitle { get; internal set; } + /// Gets the synchronization ID for the song. public string SyncId { get; internal set; } + /// Gets the session ID for the song. public string SessionId { get; internal set; } + /// Gets the duration for the song. public TimeSpan? Duration { get; internal set; } internal SpotifyGame() { } + /// Gets the name of the song. public override string ToString() => Name; private string DebuggerDisplay => $"{Name} (Spotify)"; } diff --git a/src/Discord.Net.Core/Entities/Activities/StreamingGame.cs b/src/Discord.Net.Core/Entities/Activities/StreamingGame.cs index afbc24cd9..a50e4686b 100644 --- a/src/Discord.Net.Core/Entities/Activities/StreamingGame.cs +++ b/src/Discord.Net.Core/Entities/Activities/StreamingGame.cs @@ -1,10 +1,12 @@ -using System.Diagnostics; +using System.Diagnostics; namespace Discord { + /// A user's activity for streaming on services such as Twitch. [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class StreamingGame : Game { + /// Gets the URL of the stream. public string Url { get; internal set; } public StreamingGame(string name, string url) @@ -14,7 +16,8 @@ namespace Discord Type = ActivityType.Streaming; } + /// Gets the name of the stream. public override string ToString() => Name; private string DebuggerDisplay => $"{Name} ({Url})"; } -} \ No newline at end of file +} diff --git a/src/Discord.Net.Core/Entities/CacheMode.cs b/src/Discord.Net.Core/Entities/CacheMode.cs index c4342eea2..a68a89174 100644 --- a/src/Discord.Net.Core/Entities/CacheMode.cs +++ b/src/Discord.Net.Core/Entities/CacheMode.cs @@ -1,5 +1,6 @@ namespace Discord { + /// Specifies the cache mode that should be used. public enum CacheMode { /// Allows the object to be downloaded if it does not exist in the current cache. diff --git a/src/Discord.Net.Core/Entities/Channels/Direction.cs b/src/Discord.Net.Core/Entities/Channels/Direction.cs index 5d8d5e621..750d928e5 100644 --- a/src/Discord.Net.Core/Entities/Channels/Direction.cs +++ b/src/Discord.Net.Core/Entities/Channels/Direction.cs @@ -1,9 +1,13 @@ -namespace Discord +namespace Discord { + /// Specifies the direction of where message(s) should be gotten from. public enum Direction { + /// The message(s) should be retrieved before a message. Before, + /// The message(s) should be retrieved after a message. After, + /// The message(s) should be retrieved around a message. Around } } diff --git a/src/Discord.Net.Core/Entities/Guilds/DefaultMessageNotifications.cs b/src/Discord.Net.Core/Entities/Guilds/DefaultMessageNotifications.cs index a5cabc117..4cefa0e0a 100644 --- a/src/Discord.Net.Core/Entities/Guilds/DefaultMessageNotifications.cs +++ b/src/Discord.Net.Core/Entities/Guilds/DefaultMessageNotifications.cs @@ -1,5 +1,6 @@ -namespace Discord +namespace Discord { + /// Specifies the default message notification behavior the guild uses. public enum DefaultMessageNotifications { /// By default, all messages will trigger notifications. diff --git a/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs b/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs index 62bb8dfa9..5c1deb91e 100644 --- a/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs +++ b/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to modify the widget of an with the specified parameters. + /// Properties that are used to modify the widget of an with the specified changes. /// public class GuildEmbedProperties { diff --git a/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs b/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs index f329e78e6..588a99eaf 100644 --- a/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs +++ b/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs @@ -1,9 +1,13 @@ -namespace Discord +namespace Discord { + /// Properties used to modify an with the specified changes. public class GuildIntegrationProperties { + /// Gets or sets the behavior when an integration subscription lapses. public Optional ExpireBehavior { get; set; } + /// Gets or sets the period (in seconds) where the integration will ignore lapsed subscriptions. public Optional ExpireGracePeriod { get; set; } + /// Gets or sets whether emoticons should be synced for this integration. public Optional EnableEmoticons { get; set; } } } diff --git a/src/Discord.Net.Core/Entities/Guilds/MfaLevel.cs b/src/Discord.Net.Core/Entities/Guilds/MfaLevel.cs index 1dfef17d5..0f590a9cc 100644 --- a/src/Discord.Net.Core/Entities/Guilds/MfaLevel.cs +++ b/src/Discord.Net.Core/Entities/Guilds/MfaLevel.cs @@ -1,5 +1,6 @@ -namespace Discord +namespace Discord { + /// Specifies the guild's Multi-Factor Authentication (MFA) level requirement. public enum MfaLevel { /// Users have no additional MFA restriction on this guild. diff --git a/src/Discord.Net.Core/Entities/Guilds/PermissionTarget.cs b/src/Discord.Net.Core/Entities/Guilds/PermissionTarget.cs index 96595fb69..448abaf86 100644 --- a/src/Discord.Net.Core/Entities/Guilds/PermissionTarget.cs +++ b/src/Discord.Net.Core/Entities/Guilds/PermissionTarget.cs @@ -1,8 +1,11 @@ -namespace Discord +namespace Discord { + /// Specifies the target of the permission. public enum PermissionTarget { + /// The target of the permission is a role. Role, + /// The target of the permission is a user. User } } diff --git a/src/Discord.Net.Core/Entities/Guilds/VerificationLevel.cs b/src/Discord.Net.Core/Entities/Guilds/VerificationLevel.cs index ac51fe927..22e8305c3 100644 --- a/src/Discord.Net.Core/Entities/Guilds/VerificationLevel.cs +++ b/src/Discord.Net.Core/Entities/Guilds/VerificationLevel.cs @@ -1,5 +1,6 @@ -namespace Discord +namespace Discord { + /// Specifies the verification level the guild uses. public enum VerificationLevel { /// Users have no additional restrictions on sending messages to this guild. diff --git a/src/Discord.Net.Core/Entities/IDeletable.cs b/src/Discord.Net.Core/Entities/IDeletable.cs index ba22a537a..0269b19f5 100644 --- a/src/Discord.Net.Core/Entities/IDeletable.cs +++ b/src/Discord.Net.Core/Entities/IDeletable.cs @@ -1,7 +1,8 @@ -using System.Threading.Tasks; +using System.Threading.Tasks; namespace Discord { + /// Represents whether the object is deletable or not. public interface IDeletable { /// Deletes this object and all its children. diff --git a/src/Discord.Net.Core/Entities/IMentionable.cs b/src/Discord.Net.Core/Entities/IMentionable.cs index abccc4480..87235fb6e 100644 --- a/src/Discord.Net.Core/Entities/IMentionable.cs +++ b/src/Discord.Net.Core/Entities/IMentionable.cs @@ -1,5 +1,6 @@ -namespace Discord +namespace Discord { + /// Represents whether the object is mentionable or not. public interface IMentionable { /// Returns a special string used to mention this object. diff --git a/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs b/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs index 5b099b5ac..2287c56f3 100644 --- a/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs +++ b/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs @@ -2,6 +2,7 @@ using System; namespace Discord { + /// Represents a Discord snowflake entity. public interface ISnowflakeEntity : IEntity { DateTimeOffset CreatedAt { get; } diff --git a/src/Discord.Net.Core/Entities/IUpdateable.cs b/src/Discord.Net.Core/Entities/IUpdateable.cs index b0f51aee7..303db25c0 100644 --- a/src/Discord.Net.Core/Entities/IUpdateable.cs +++ b/src/Discord.Net.Core/Entities/IUpdateable.cs @@ -1,7 +1,8 @@ -using System.Threading.Tasks; +using System.Threading.Tasks; namespace Discord { + /// Represents whether the object is updatable or not. public interface IUpdateable { /// Updates this object's properties with its current state. diff --git a/src/Discord.Net.Core/Entities/ImageFormat.cs b/src/Discord.Net.Core/Entities/ImageFormat.cs index 0b74a443e..e6f80110d 100644 --- a/src/Discord.Net.Core/Entities/ImageFormat.cs +++ b/src/Discord.Net.Core/Entities/ImageFormat.cs @@ -1,6 +1,6 @@ namespace Discord { - /// The type of format for the image to return. + /// Specifies the type of format the image should return in. public enum ImageFormat { Auto, diff --git a/src/Discord.Net.Core/Entities/Messages/Embed.cs b/src/Discord.Net.Core/Entities/Messages/Embed.cs index 5fae7acde..6ea7c0bd5 100644 --- a/src/Discord.Net.Core/Entities/Messages/Embed.cs +++ b/src/Discord.Net.Core/Entities/Messages/Embed.cs @@ -1,4 +1,4 @@ -using System; +using System; using System.Collections.Immutable; using System.Diagnostics; using System.Linq; @@ -8,19 +8,32 @@ namespace Discord [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class Embed : IEmbed { + /// public EmbedType Type { get; } + /// public string Description { get; internal set; } + /// public string Url { get; internal set; } + /// public string Title { get; internal set; } + /// public DateTimeOffset? Timestamp { get; internal set; } + /// public Color? Color { get; internal set; } + /// public EmbedImage? Image { get; internal set; } + /// public EmbedVideo? Video { get; internal set; } + /// public EmbedAuthor? Author { get; internal set; } + /// public EmbedFooter? Footer { get; internal set; } + /// public EmbedProvider? Provider { get; internal set; } + /// public EmbedThumbnail? Thumbnail { get; internal set; } + /// public ImmutableArray Fields { get; internal set; } internal Embed(EmbedType type) diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedAuthor.cs b/src/Discord.Net.Core/Entities/Messages/EmbedAuthor.cs index c59473704..9d7cfdf18 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedAuthor.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedAuthor.cs @@ -1,14 +1,19 @@ -using System; +using System; using System.Diagnostics; namespace Discord { + /// An author field for an . [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedAuthor { + /// Gets the name of the author field. public string Name { get; internal set; } + /// Gets the URL of the author field. public string Url { get; internal set; } + /// Gets the icon URL of the author field. public string IconUrl { get; internal set; } + /// Gets the proxified icon URL of the author field. public string ProxyIconUrl { get; internal set; } internal EmbedAuthor(string name, string url, string iconUrl, string proxyIconUrl) diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs b/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs index baabe50c6..bab72fe1b 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs @@ -1,12 +1,10 @@ -using System; +using System; using System.Collections.Generic; using System.Collections.Immutable; namespace Discord { - /// - /// Builder for creating an to be sent. - /// + /// A builder for creating an to be sent. public class EmbedBuilder { private readonly Embed _embed; diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedField.cs b/src/Discord.Net.Core/Entities/Messages/EmbedField.cs index f7c1f8348..2bc4ae436 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedField.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedField.cs @@ -1,12 +1,16 @@ -using System.Diagnostics; +using System.Diagnostics; namespace Discord { + /// A field for an . [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedField { + /// Gets the name of the field. public string Name { get; internal set; } + /// Gets the value of the field. public string Value { get; internal set; } + /// Gets whether the field is inline inside an or not. public bool Inline { get; internal set; } internal EmbedField(string name, string value, bool inline) diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedFooter.cs b/src/Discord.Net.Core/Entities/Messages/EmbedFooter.cs index 29d85cd90..591c90642 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedFooter.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedFooter.cs @@ -1,13 +1,17 @@ -using System; +using System; using System.Diagnostics; namespace Discord { + /// A footer field for an . [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedFooter { + /// Gets the text of the footer. public string Text { get; internal set; } + /// Gets the icon URL of the footer. public string IconUrl { get; internal set; } + /// Gets the proxified icon URL of the footer. public string ProxyUrl { get; internal set; } internal EmbedFooter(string text, string iconUrl, string proxyUrl) diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedImage.cs b/src/Discord.Net.Core/Entities/Messages/EmbedImage.cs index f21d42c0c..0c59f6407 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedImage.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedImage.cs @@ -1,14 +1,19 @@ -using System; +using System; using System.Diagnostics; namespace Discord { + /// An image for an . [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedImage { + /// Gets the URL of the image. public string Url { get; } + /// Gets the proxified URL of the image. public string ProxyUrl { get; } + /// Gets the height of the image if any is set. public int? Height { get; } + /// Gets the width of the image if any is set. public int? Width { get; } internal EmbedImage(string url, string proxyUrl, int? height, int? width) diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedProvider.cs b/src/Discord.Net.Core/Entities/Messages/EmbedProvider.cs index 24722b158..f536224b0 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedProvider.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedProvider.cs @@ -1,12 +1,15 @@ -using System; +using System; using System.Diagnostics; namespace Discord { + /// A provider field for an . [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedProvider { + /// Gets the name of the provider. public string Name { get; } + /// Gets the URL of the provider. public string Url { get; } internal EmbedProvider(string name, string url) diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedThumbnail.cs b/src/Discord.Net.Core/Entities/Messages/EmbedThumbnail.cs index 209a93e37..6196b1342 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedThumbnail.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedThumbnail.cs @@ -1,14 +1,19 @@ -using System; +using System; using System.Diagnostics; namespace Discord { + /// A thumbnail featured in an . [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedThumbnail { + /// Gets the URL of the thumbnail. public string Url { get; } + /// Gets the proxified URL of the thumbnail. public string ProxyUrl { get; } + /// Gets the height of the thumbnail if any is set. public int? Height { get; } + /// Gets the width of the thumbnail if any is set. public int? Width { get; } internal EmbedThumbnail(string url, string proxyUrl, int? height, int? width) diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedType.cs b/src/Discord.Net.Core/Entities/Messages/EmbedType.cs index 5bb2653e2..7bfc9ec3d 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedType.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedType.cs @@ -1,15 +1,25 @@ namespace Discord { + /// Specifies the type of embed. public enum EmbedType { + /// An unknown embed type. Unknown = -1, + /// A rich embed type. Rich, + /// A link embed type. Link, + /// A video embed type. Video, + /// An image embed type. Image, + /// A GIFV embed type. Gifv, + /// An article embed type. Article, + /// A tweet embed type. Tweet, + /// A HTML embed type. Html, } } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedVideo.cs b/src/Discord.Net.Core/Entities/Messages/EmbedVideo.cs index f00681d89..1ee03b70c 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedVideo.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedVideo.cs @@ -1,13 +1,17 @@ -using System; +using System; using System.Diagnostics; namespace Discord { + /// A video featured in an . [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedVideo { + /// Gets the URL of the video. public string Url { get; } + /// Gets the height of the video if there is any. public int? Height { get; } + /// Gets the weight of the video if there is any. public int? Width { get; } internal EmbedVideo(string url, int? height, int? width) diff --git a/src/Discord.Net.Core/Entities/Messages/IAttachment.cs b/src/Discord.Net.Core/Entities/Messages/IAttachment.cs index 90b3f28ba..b1eb67b5b 100644 --- a/src/Discord.Net.Core/Entities/Messages/IAttachment.cs +++ b/src/Discord.Net.Core/Entities/Messages/IAttachment.cs @@ -1,22 +1,22 @@ namespace Discord { - /// The interface that defines an attachment object. + /// Represents a Discord attachment object. public interface IAttachment { - /// The snowflake ID of the attachment. + /// Gets the snowflake ID of the attachment. ulong Id { get; } - /// The filename of the attachment. + /// Gets the filename of the attachment. string Filename { get; } - /// The URL of the attachment. + /// Gets the URL of the attachment. string Url { get; } - /// The proxied URL of the attachment. + /// Gets the proxied URL of the attachment. string ProxyUrl { get; } - /// The file size of the attachment. + /// Gets the file size of the attachment. int Size { get; } - /// The height of the attachment if it is an image, or return when it is not. + /// Gets the height of the attachment if it is an image, or return when it is not. int? Height { get; } - /// The width of the attachment if it is an image, or return when it is not. + /// Gets the width of the attachment if it is an image, or return when it is not. int? Width { get; } } } diff --git a/src/Discord.Net.Core/Entities/Messages/IEmbed.cs b/src/Discord.Net.Core/Entities/Messages/IEmbed.cs index f390c4c28..77b43c25d 100644 --- a/src/Discord.Net.Core/Entities/Messages/IEmbed.cs +++ b/src/Discord.Net.Core/Entities/Messages/IEmbed.cs @@ -1,22 +1,36 @@ -using System; +using System; using System.Collections.Immutable; namespace Discord { + /// Represents a Discord embed object. public interface IEmbed { + /// Gets the title URL of the embed. string Url { get; } + /// Gets the title of the embed. string Title { get; } + /// Gets the description of the embed. string Description { get; } + /// Gets the type of the embed. EmbedType Type { get; } + /// Gets the timestamp of the embed. DateTimeOffset? Timestamp { get; } + /// Gets the sidebar color of the embed. Color? Color { get; } + /// Gets the image of the embed. EmbedImage? Image { get; } + /// Gets the video of the embed. EmbedVideo? Video { get; } + /// Gets the author field of the embed. EmbedAuthor? Author { get; } + /// Gets the footer field of the embed. EmbedFooter? Footer { get; } + /// Gets the provider of the embed. EmbedProvider? Provider { get; } + /// Gets the thumbnail featured in the embed. EmbedThumbnail? Thumbnail { get; } + /// Gets the fields of the embed. ImmutableArray Fields { get; } } } diff --git a/src/Discord.Net.Core/Entities/Messages/IMessage.cs b/src/Discord.Net.Core/Entities/Messages/IMessage.cs index 4266f893a..7d4a749f7 100644 --- a/src/Discord.Net.Core/Entities/Messages/IMessage.cs +++ b/src/Discord.Net.Core/Entities/Messages/IMessage.cs @@ -1,8 +1,9 @@ -using System; +using System; using System.Collections.Generic; namespace Discord { + /// Represents a Discord message object. public interface IMessage : ISnowflakeEntity, IDeletable { /// Gets the type of this system message. diff --git a/src/Discord.Net.Core/Entities/Messages/IReaction.cs b/src/Discord.Net.Core/Entities/Messages/IReaction.cs index 37ead42ae..6325901f8 100644 --- a/src/Discord.Net.Core/Entities/Messages/IReaction.cs +++ b/src/Discord.Net.Core/Entities/Messages/IReaction.cs @@ -1,7 +1,9 @@ -namespace Discord +namespace Discord { + /// Represents a Discord reaction object. public interface IReaction { + /// The used in the reaction. IEmote Emote { get; } } } diff --git a/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs b/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs index 52df187f8..ab58ca008 100644 --- a/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs +++ b/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs @@ -1,9 +1,10 @@ -using System; +using System; using System.Collections.Generic; using System.Threading.Tasks; namespace Discord { + /// A Discord message object. public interface IUserMessage : IMessage { /// Modifies this message. diff --git a/src/Discord.Net.Core/Entities/Messages/MessageProperties.cs b/src/Discord.Net.Core/Entities/Messages/MessageProperties.cs index bb6dcbe0f..788ea25a5 100644 --- a/src/Discord.Net.Core/Entities/Messages/MessageProperties.cs +++ b/src/Discord.Net.Core/Entities/Messages/MessageProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to modify a message with the specified parameters. + /// Properties that are used to modify an with the specified changes. /// /// /// The content of a message can be cleared with String.Empty; if and only if an Embed is present. diff --git a/src/Discord.Net.Core/Entities/Messages/MessageSource.cs b/src/Discord.Net.Core/Entities/Messages/MessageSource.cs index 1cb2f8b94..7dff168c4 100644 --- a/src/Discord.Net.Core/Entities/Messages/MessageSource.cs +++ b/src/Discord.Net.Core/Entities/Messages/MessageSource.cs @@ -1,10 +1,15 @@ namespace Discord { + /// Specifies the source of the Discord message. public enum MessageSource { + /// The message is sent by the system. System, + /// The message is sent by a user. User, + /// The message is sent by a bot. Bot, + /// The message is sent by a webhook. Webhook } } diff --git a/src/Discord.Net.Core/Entities/Messages/MessageType.cs b/src/Discord.Net.Core/Entities/Messages/MessageType.cs index 687e69e14..167f9fed3 100644 --- a/src/Discord.Net.Core/Entities/Messages/MessageType.cs +++ b/src/Discord.Net.Core/Entities/Messages/MessageType.cs @@ -1,13 +1,21 @@ -namespace Discord +namespace Discord { + /// Specifies the type of message. public enum MessageType { + /// The default message type. Default = 0, + /// The message when a recipient is added. RecipientAdd = 1, + /// The message when a recipient is removed. RecipientRemove = 2, + /// The message when a user is called. Call = 3, + /// The message when a channel name is changed. ChannelNameChange = 4, + /// The message when a channel icon is changed. ChannelIconChange = 5, + /// The message when another message is pinned. ChannelPinnedMessage = 6 } } diff --git a/src/Discord.Net.Core/Entities/Messages/ReactionMetadata.cs b/src/Discord.Net.Core/Entities/Messages/ReactionMetadata.cs index 005276202..c34a34729 100644 --- a/src/Discord.Net.Core/Entities/Messages/ReactionMetadata.cs +++ b/src/Discord.Net.Core/Entities/Messages/ReactionMetadata.cs @@ -1,11 +1,12 @@ -namespace Discord +namespace Discord { + /// A metadata containing reaction information. public struct ReactionMetadata { - /// Gets the number of reactions + /// Gets the number of reactions. public int ReactionCount { get; internal set; } - /// Returns true if the current user has used this reaction + /// Returns true if the current user has used this reaction. public bool IsMe { get; internal set; } } } diff --git a/src/Discord.Net.Core/Entities/Messages/TagHandling.cs b/src/Discord.Net.Core/Entities/Messages/TagHandling.cs index 492f05879..667f7241b 100644 --- a/src/Discord.Net.Core/Entities/Messages/TagHandling.cs +++ b/src/Discord.Net.Core/Entities/Messages/TagHandling.cs @@ -1,13 +1,21 @@ -namespace Discord +namespace Discord { + /// Specifies the handling type the tag should use. public enum TagHandling { + /// Tag handling is ignored. Ignore = 0, //<@53905483156684800> -> <@53905483156684800> - Remove, //<@53905483156684800> -> + /// Removes the tag entirely. + Remove, //<@53905483156684800> -> + /// Resolves to username (e.g. @User). Name, //<@53905483156684800> -> @Voltana + /// Resolves to username without mention prefix (e.g. User). NameNoPrefix, //<@53905483156684800> -> Voltana + /// Resolves to username with discriminator value. (e.g. @User#0001). FullName, //<@53905483156684800> -> @Voltana#8252 + /// Resolves to username with discriminator value without mention prefix. (e.g. User#0001). FullNameNoPrefix, //<@53905483156684800> -> Voltana#8252 + /// Sanitizes the tag. Sanitize //<@53905483156684800> -> <@53905483156684800> (w/ nbsp) } } diff --git a/src/Discord.Net.Core/Entities/Messages/TagType.cs b/src/Discord.Net.Core/Entities/Messages/TagType.cs index 2d93bb3e3..177157251 100644 --- a/src/Discord.Net.Core/Entities/Messages/TagType.cs +++ b/src/Discord.Net.Core/Entities/Messages/TagType.cs @@ -1,12 +1,19 @@ -namespace Discord +namespace Discord { + /// Specifies the type of Discord tag. public enum TagType { + /// The object is an user mention. UserMention, + /// The object is a channel mention. ChannelMention, + /// The object is a role mention. RoleMention, + /// The object is an everyone mention. EveryoneMention, + /// The object is a here mention. HereMention, + /// The object is an emoji. Emoji } } diff --git a/src/Discord.Net.Core/Entities/Permissions/ChannelPermission.cs b/src/Discord.Net.Core/Entities/Permissions/ChannelPermission.cs index 3db506487..498aa5ef8 100644 --- a/src/Discord.Net.Core/Entities/Permissions/ChannelPermission.cs +++ b/src/Discord.Net.Core/Entities/Permissions/ChannelPermission.cs @@ -2,6 +2,7 @@ using System; namespace Discord { + /// Defines the available permissions for a channel. [FlagsAttribute] public enum ChannelPermission : ulong { diff --git a/src/Discord.Net.Core/Entities/Permissions/GuildPermission.cs b/src/Discord.Net.Core/Entities/Permissions/GuildPermission.cs index 8469fd304..f94ff121e 100644 --- a/src/Discord.Net.Core/Entities/Permissions/GuildPermission.cs +++ b/src/Discord.Net.Core/Entities/Permissions/GuildPermission.cs @@ -1,7 +1,8 @@ -using System; +using System; namespace Discord { + /// Defines the available permissions for a channel. [FlagsAttribute] public enum GuildPermission : ulong { diff --git a/src/Discord.Net.Core/Entities/Permissions/PermValue.cs b/src/Discord.Net.Core/Entities/Permissions/PermValue.cs index fe048b016..6cea8270d 100644 --- a/src/Discord.Net.Core/Entities/Permissions/PermValue.cs +++ b/src/Discord.Net.Core/Entities/Permissions/PermValue.cs @@ -1,9 +1,13 @@ -namespace Discord +namespace Discord { + /// Specifies the permission value. public enum PermValue { + /// Allows this permission. Allow, + /// Denies this permission. Deny, + /// Inherits the permission settings. Inherit } } diff --git a/src/Discord.Net.Core/Entities/Roles/Color.cs b/src/Discord.Net.Core/Entities/Roles/Color.cs index 89e76df6d..ffd391e5a 100644 --- a/src/Discord.Net.Core/Entities/Roles/Color.cs +++ b/src/Discord.Net.Core/Entities/Roles/Color.cs @@ -3,6 +3,7 @@ using System.Diagnostics; namespace Discord { + /// A color object that Discord uses. [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public struct Color { diff --git a/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs index 0c8afa24c..852651beb 100644 --- a/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs +++ b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs @@ -1,10 +1,11 @@ -namespace Discord +namespace Discord { + /// Properties that are used to reorder an . public class ReorderRoleProperties { - /// The id of the role to be edited + /// Gets the ID of the role to be edited. public ulong Id { get; } - /// The new zero-based position of the role. + /// Gets the new zero-based position of the role. public int Position { get; } public ReorderRoleProperties(ulong id, int pos) diff --git a/src/Discord.Net.Core/Entities/Roles/RoleProperties.cs b/src/Discord.Net.Core/Entities/Roles/RoleProperties.cs index 8950a2634..82d57ffa9 100644 --- a/src/Discord.Net.Core/Entities/Roles/RoleProperties.cs +++ b/src/Discord.Net.Core/Entities/Roles/RoleProperties.cs @@ -1,7 +1,7 @@ -namespace Discord +namespace Discord { /// - /// Modify an IRole with the specified parameters + /// Properties that are used to modify an with the specified changes. /// /// /// @@ -16,39 +16,39 @@ public class RoleProperties { /// - /// The name of the role + /// Gets or sets the name of the role. /// /// /// If this role is the EveryoneRole, this value may not be set. /// public Optional Name { get; set; } /// - /// The role's GuildPermissions + /// Gets or sets the role's . /// public Optional Permissions { get; set; } /// - /// The position of the role. This is 0-based! + /// Gets or sets the position of the role. This is 0-based! /// /// /// If this role is the EveryoneRole, this value may not be set. /// public Optional Position { get; set; } /// - /// The color of the Role. + /// Gets or sets the color of the Role. /// /// /// If this role is the EveryoneRole, this value may not be set. /// public Optional Color { get; set; } /// - /// Whether or not this role should be displayed independently in the userlist. + /// Gets or sets whether or not this role should be displayed independently in the userlist. /// /// /// If this role is the EveryoneRole, this value may not be set. /// public Optional Hoist { get; set; } /// - /// Whether or not this role can be mentioned. + /// Gets or sets whether or not this role can be mentioned. /// /// /// If this role is the EveryoneRole, this value may not be set. diff --git a/src/Discord.Net.Core/Entities/Users/IGroupUser.cs b/src/Discord.Net.Core/Entities/Users/IGroupUser.cs index dd046a5a8..f3d44b583 100644 --- a/src/Discord.Net.Core/Entities/Users/IGroupUser.cs +++ b/src/Discord.Net.Core/Entities/Users/IGroupUser.cs @@ -1,5 +1,6 @@ -namespace Discord +namespace Discord { + /// Represents a Discord user that is in a group. public interface IGroupUser : IUser, IVoiceState { ///// Kicks this user from this group. diff --git a/src/Discord.Net.Core/Entities/Users/IGuildUser.cs b/src/Discord.Net.Core/Entities/Users/IGuildUser.cs index 57cad1333..97ef7d5c1 100644 --- a/src/Discord.Net.Core/Entities/Users/IGuildUser.cs +++ b/src/Discord.Net.Core/Entities/Users/IGuildUser.cs @@ -1,10 +1,10 @@ -using System; +using System; using System.Collections.Generic; using System.Threading.Tasks; namespace Discord { - /// A Guild-User pairing. + /// Represents a Discord user that is in a guild. public interface IGuildUser : IUser, IVoiceState { /// Gets when this user joined this guild. diff --git a/src/Discord.Net.Core/Entities/Users/IPresence.cs b/src/Discord.Net.Core/Entities/Users/IPresence.cs index 25adcc9c4..9d3a5ecb9 100644 --- a/src/Discord.Net.Core/Entities/Users/IPresence.cs +++ b/src/Discord.Net.Core/Entities/Users/IPresence.cs @@ -1,5 +1,6 @@ -namespace Discord +namespace Discord { + /// Represents a Discord user's presence status. public interface IPresence { /// Gets the activity this user is currently doing. @@ -7,4 +8,4 @@ /// Gets the current status of this user. UserStatus Status { get; } } -} \ No newline at end of file +} diff --git a/src/Discord.Net.Core/Entities/Users/ISelfUser.cs b/src/Discord.Net.Core/Entities/Users/ISelfUser.cs index 7b91d4e3a..a1078dd35 100644 --- a/src/Discord.Net.Core/Entities/Users/ISelfUser.cs +++ b/src/Discord.Net.Core/Entities/Users/ISelfUser.cs @@ -3,6 +3,7 @@ using System.Threading.Tasks; namespace Discord { + /// Represents a logged-in Discord user. public interface ISelfUser : IUser { /// Gets the email associated with this user. @@ -14,4 +15,4 @@ namespace Discord Task ModifyAsync(Action func, RequestOptions options = null); } -} \ No newline at end of file +} diff --git a/src/Discord.Net.Core/Entities/Users/IUser.cs b/src/Discord.Net.Core/Entities/Users/IUser.cs index e3f270f6f..6d4ddf6af 100644 --- a/src/Discord.Net.Core/Entities/Users/IUser.cs +++ b/src/Discord.Net.Core/Entities/Users/IUser.cs @@ -2,6 +2,7 @@ using System.Threading.Tasks; namespace Discord { + /// Represents a Discord user. public interface IUser : ISnowflakeEntity, IMentionable, IPresence { /// Gets the id of this user's avatar. diff --git a/src/Discord.Net.Core/Entities/Users/IWebhookUser.cs b/src/Discord.Net.Core/Entities/Users/IWebhookUser.cs index be769b944..a29debf0f 100644 --- a/src/Discord.Net.Core/Entities/Users/IWebhookUser.cs +++ b/src/Discord.Net.Core/Entities/Users/IWebhookUser.cs @@ -1,5 +1,6 @@ -namespace Discord +namespace Discord { + /// Represents a Webhook Discord user. public interface IWebhookUser : IGuildUser { ulong WebhookId { get; } diff --git a/src/Discord.Net.Core/Entities/Users/SelfUserProperties.cs b/src/Discord.Net.Core/Entities/Users/SelfUserProperties.cs index 9c4162780..9245a3616 100644 --- a/src/Discord.Net.Core/Entities/Users/SelfUserProperties.cs +++ b/src/Discord.Net.Core/Entities/Users/SelfUserProperties.cs @@ -1,7 +1,7 @@ -namespace Discord +namespace Discord { /// - /// Modify the current user with the specified arguments + /// Properties that are used to modify the with the specified changes. /// /// /// diff --git a/src/Discord.Net.Core/Entities/Users/UserStatus.cs b/src/Discord.Net.Core/Entities/Users/UserStatus.cs index 74a52a0fa..f999bf068 100644 --- a/src/Discord.Net.Core/Entities/Users/UserStatus.cs +++ b/src/Discord.Net.Core/Entities/Users/UserStatus.cs @@ -1,12 +1,19 @@ -namespace Discord +namespace Discord { + /// Defines the available Discord user status. public enum UserStatus { + /// The user is offline. Offline, + /// The user is online. Online, + /// The user is idle. Idle, + /// The user is AFK. AFK, + /// The user is busy. DoNotDisturb, + /// The user is invisible. Invisible, } } diff --git a/src/Discord.Net.Core/Entities/Webhooks/WebhookProperties.cs b/src/Discord.Net.Core/Entities/Webhooks/WebhookProperties.cs index 8759a1729..8edec02cd 100644 --- a/src/Discord.Net.Core/Entities/Webhooks/WebhookProperties.cs +++ b/src/Discord.Net.Core/Entities/Webhooks/WebhookProperties.cs @@ -1,7 +1,7 @@ -namespace Discord +namespace Discord { /// - /// Modify an with the specified parameters. + /// Properties used to modify an with the specified changes. /// /// /// @@ -16,22 +16,22 @@ public class WebhookProperties { /// - /// The default name of the webhook. + /// Gets or sets the default name of the webhook. /// public Optional Name { get; set; } /// - /// The default avatar of the webhook. + /// Gets or sets the default avatar of the webhook. /// public Optional Image { get; set; } /// - /// The channel for this webhook. + /// Gets or sets the channel for this webhook. /// /// /// This field is not used when authenticated with . /// public Optional Channel { get; set; } /// - /// The channel id for this webhook. + /// Gets or sets the channel ID for this webhook. /// /// /// This field is not used when authenticated with . diff --git a/src/Discord.Net.Core/Extensions/DiscordClientExtensions.cs b/src/Discord.Net.Core/Extensions/DiscordClientExtensions.cs index ff3c7caf7..03d736c6e 100644 --- a/src/Discord.Net.Core/Extensions/DiscordClientExtensions.cs +++ b/src/Discord.Net.Core/Extensions/DiscordClientExtensions.cs @@ -1,24 +1,31 @@ -using System.Collections.Generic; +using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; namespace Discord { + /// Extensions for . public static class DiscordClientExtensions { + /// Gets the private channel with the provided ID. public static async Task GetPrivateChannelAsync(this IDiscordClient client, ulong id) => await client.GetChannelAsync(id).ConfigureAwait(false) as IPrivateChannel; + /// Gets the DM channel with the provided ID. public static async Task GetDMChannelAsync(this IDiscordClient client, ulong id) => await client.GetPrivateChannelAsync(id).ConfigureAwait(false) as IDMChannel; + /// Gets all available DM channels for the client. public static async Task> GetDMChannelsAsync(this IDiscordClient client) => (await client.GetPrivateChannelsAsync().ConfigureAwait(false)).Select(x => x as IDMChannel).Where(x => x != null); + /// Gets the group channel with the provided ID. public static async Task GetGroupChannelAsync(this IDiscordClient client, ulong id) => await client.GetPrivateChannelAsync(id).ConfigureAwait(false) as IGroupChannel; + /// Gets all available group channels for the client. public static async Task> GetGroupChannelsAsync(this IDiscordClient client) => (await client.GetPrivateChannelsAsync().ConfigureAwait(false)).Select(x => x as IGroupChannel).Where(x => x != null); + /// Gets the most optimal voice region for the client. public static async Task GetOptimalVoiceRegionAsync(this IDiscordClient discord) { var regions = await discord.GetVoiceRegionsAsync().ConfigureAwait(false); diff --git a/src/Discord.Net.Core/Extensions/EmbedBuilderExtensions.cs b/src/Discord.Net.Core/Extensions/EmbedBuilderExtensions.cs index 5ad8d8b1d..90eaf90ad 100644 --- a/src/Discord.Net.Core/Extensions/EmbedBuilderExtensions.cs +++ b/src/Discord.Net.Core/Extensions/EmbedBuilderExtensions.cs @@ -2,6 +2,7 @@ using System; namespace Discord { + /// Extensions for building an embed. public static class EmbedBuilderExtensions { /// Adds embed color based on the provided raw value. diff --git a/src/Discord.Net.Core/Logging/LogSeverity.cs b/src/Discord.Net.Core/Logging/LogSeverity.cs index 98a822425..98677dbde 100644 --- a/src/Discord.Net.Core/Logging/LogSeverity.cs +++ b/src/Discord.Net.Core/Logging/LogSeverity.cs @@ -1,5 +1,6 @@ namespace Discord { + /// Specifies the severity of the log message. public enum LogSeverity { /// diff --git a/src/Discord.Net.Core/LoginState.cs b/src/Discord.Net.Core/LoginState.cs index 42b6ecac9..49f86c9fa 100644 --- a/src/Discord.Net.Core/LoginState.cs +++ b/src/Discord.Net.Core/LoginState.cs @@ -1,10 +1,15 @@ -namespace Discord +namespace Discord { + /// Specifies the state of the client's login status. public enum LoginState : byte { + /// The client is currently logged out. LoggedOut, + /// The client is currently logging in. LoggingIn, + /// The client is currently logged in. LoggedIn, + /// The client is currently logging out. LoggingOut } } diff --git a/src/Discord.Net.Core/TokenType.cs b/src/Discord.Net.Core/TokenType.cs index 62181420a..dc30c418a 100644 --- a/src/Discord.Net.Core/TokenType.cs +++ b/src/Discord.Net.Core/TokenType.cs @@ -2,6 +2,7 @@ using System; namespace Discord { + /// Specifies the type of token to use with the client. public enum TokenType { [Obsolete("User logins are deprecated and may result in a ToS strike against your account - please see https://github.com/RogueException/Discord.Net/issues/827", error: true)]