From 1d2db3a61cae77318bf5abd1dbcf005a15fb9c80 Mon Sep 17 00:00:00 2001 From: Hsu Still <341464@gmail.com> Date: Wed, 28 Mar 2018 02:47:38 +0800 Subject: [PATCH] Add XMLDocs --- .../Preconditions/RequireContextAttribute.cs | 11 ++-- src/Discord.Net.Commands/Results/IResult.cs | 1 + .../Entities/Activities/Game.cs | 4 ++ .../Entities/Messages/EmbedBuilder.cs | 55 +++++++++++++++++++ .../Entities/Messages/IAttachment.cs | 2 +- .../Entities/Messages/Attachment.cs | 14 ++--- .../Commands/ShardedCommandContext.cs | 6 +- .../Commands/SocketCommandContext.cs | 1 - 8 files changed, 80 insertions(+), 14 deletions(-) diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs index bf5d081ce..c66cd7c12 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs @@ -4,25 +4,28 @@ using Microsoft.Extensions.DependencyInjection; namespace Discord.Commands { + /// Defines the type of command context. [Flags] public enum ContextType { + /// Specifies the command to be executed within a guild. Guild = 0x01, + /// Specifies the command to be executed within a DM. DM = 0x02, + /// Specifies the command to be executed within a group. Group = 0x04 } /// - /// Requires the command to 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 { + /// Gets the context required to execute the command. public ContextType Contexts { get; } - /// - /// Requires that the command be invoked in the specified context. - /// + /// Requires that the command be invoked in the specified context. /// The type of context the command can be invoked in. Multiple contexts can be specified by ORing the contexts together. /// /// diff --git a/src/Discord.Net.Commands/Results/IResult.cs b/src/Discord.Net.Commands/Results/IResult.cs index cc5d4c3be..d5b9ffe0f 100644 --- a/src/Discord.Net.Commands/Results/IResult.cs +++ b/src/Discord.Net.Commands/Results/IResult.cs @@ -1,5 +1,6 @@ namespace Discord.Commands { + /// Represents the information of command execution result. public interface IResult { /// Describes the error type that may have occurred during the operation. diff --git a/src/Discord.Net.Core/Entities/Activities/Game.cs b/src/Discord.Net.Core/Entities/Activities/Game.cs index 5c5bd98b5..c75d96969 100644 --- a/src/Discord.Net.Core/Entities/Activities/Game.cs +++ b/src/Discord.Net.Core/Entities/Activities/Game.cs @@ -12,12 +12,16 @@ namespace Discord public ActivityType Type { get; internal set; } internal Game() { } + /// Creates a with the provided name and . + /// The name of the game. + /// The type of activity. Default is . public Game(string name, ActivityType type = ActivityType.Playing) { Name = name; Type = type; } + /// Returns the name of the . public override string ToString() => Name; private string DebuggerDisplay => Name; } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs b/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs index bab72fe1b..1fa8c85f9 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs @@ -9,17 +9,23 @@ namespace Discord { private readonly Embed _embed; + /// The maximum number of fields allowed by Discord. public const int MaxFieldCount = 25; + /// The maximum length of title allowed by Discord. public const int MaxTitleLength = 256; + /// The maximum length of description allowed by Discord. public const int MaxDescriptionLength = 2048; + /// The maximum length of total characters allowed by Discord. public const int MaxEmbedLength = 6000; // user bot limit is 2000, but we don't validate that here. + /// Creates a new . public EmbedBuilder() { _embed = new Embed(EmbedType.Rich); Fields = new List(); } + /// Gets or sets the title of an . public string Title { get => _embed.Title; @@ -30,6 +36,7 @@ namespace Discord } } + /// Gets or sets the description of an . public string Description { get => _embed.Description; @@ -40,6 +47,7 @@ namespace Discord } } + /// Gets or sets the URL of an . public string Url { get => _embed.Url; @@ -49,6 +57,7 @@ namespace Discord _embed.Url = value; } } + /// Gets or sets the thumbnail URL of an . public string ThumbnailUrl { get => _embed.Thumbnail?.Url; @@ -58,6 +67,7 @@ namespace Discord _embed.Thumbnail = new EmbedThumbnail(value, null, null, null); } } + /// Gets or sets the image URL of an . public string ImageUrl { get => _embed.Image?.Url; @@ -67,12 +77,17 @@ namespace Discord _embed.Image = new EmbedImage(value, null, null, null); } } + /// Gets or sets the timestamp of an . public DateTimeOffset? Timestamp { get => _embed.Timestamp; set { _embed.Timestamp = value; } } + /// Gets or sets the sidebar color of an . public Color? Color { get => _embed.Color; set { _embed.Color = value; } } + /// Gets or sets the of an . public EmbedAuthorBuilder Author { get; set; } + /// Gets or sets the of an . public EmbedFooterBuilder Footer { get; set; } private List _fields; + /// Gets or sets the list of of an . public List Fields { get => _fields; @@ -85,52 +100,71 @@ namespace Discord } } + /// Sets the title of an . + /// The title to be set. public EmbedBuilder WithTitle(string title) { Title = title; return this; } + /// Sets the description of an . + /// The description to be set. public EmbedBuilder WithDescription(string description) { Description = description; return this; } + /// Sets the URL of an . + /// The URL to be set. public EmbedBuilder WithUrl(string url) { Url = url; return this; } + /// Sets the thumbnail URL of an . + /// The thumbnail URL to be set. public EmbedBuilder WithThumbnailUrl(string thumbnailUrl) { ThumbnailUrl = thumbnailUrl; return this; } + /// Sets the image URL of an . + /// The image URL to be set. public EmbedBuilder WithImageUrl(string imageUrl) { ImageUrl = imageUrl; return this; } + /// Sets the timestamp of an to the current time. public EmbedBuilder WithCurrentTimestamp() { Timestamp = DateTimeOffset.UtcNow; return this; } + /// Sets the timestamp of an . + /// The timestamp to be set. public EmbedBuilder WithTimestamp(DateTimeOffset dateTimeOffset) { Timestamp = dateTimeOffset; return this; } + /// Sets the sidebar color of an . + /// The color to be set. public EmbedBuilder WithColor(Color color) { Color = color; return this; } + /// Sets the of an . + /// The author builder class containing the author field properties. public EmbedBuilder WithAuthor(EmbedAuthorBuilder author) { Author = author; return this; } + /// Sets the author field of an with the provided properties. + /// The delegate containing the author field properties. public EmbedBuilder WithAuthor(Action action) { var author = new EmbedAuthorBuilder(); @@ -138,6 +172,10 @@ namespace Discord Author = author; return this; } + /// Sets the author field of an with the provided name, icon URL, and URL. + /// The title of the author field. + /// The icon URL of the author field. + /// The URL of the author field. public EmbedBuilder WithAuthor(string name, string iconUrl = null, string url = null) { var author = new EmbedAuthorBuilder @@ -149,11 +187,15 @@ namespace Discord Author = author; return this; } + /// Sets the of an . + /// The footer builder class containing the footer field properties. public EmbedBuilder WithFooter(EmbedFooterBuilder footer) { Footer = footer; return this; } + /// Sets the footer field of an with the provided properties. + /// The delegate containing the footer field properties. public EmbedBuilder WithFooter(Action action) { var footer = new EmbedFooterBuilder(); @@ -161,6 +203,9 @@ namespace Discord Footer = footer; return this; } + /// Sets the footer field of an with the provided name, icon URL. + /// The title of the footer field. + /// The icon URL of the footer field. public EmbedBuilder WithFooter(string text, string iconUrl = null) { var footer = new EmbedFooterBuilder @@ -172,6 +217,10 @@ namespace Discord return this; } + /// Adds an field with the provided name and value. + /// The title of the field. + /// The value of the field. + /// Indicates whether the field is in-line or not. public EmbedBuilder AddField(string name, object value, bool inline = false) { var field = new EmbedFieldBuilder() @@ -182,6 +231,8 @@ namespace Discord return this; } + /// Adds a field with the provided to an . + /// The field builder class containing the field properties. public EmbedBuilder AddField(EmbedFieldBuilder field) { if (Fields.Count >= MaxFieldCount) @@ -192,6 +243,8 @@ namespace Discord Fields.Add(field); return this; } + /// Adds an field with the provided properties. + /// The delegate containing the field properties. public EmbedBuilder AddField(Action action) { var field = new EmbedFieldBuilder(); @@ -200,6 +253,8 @@ namespace Discord return this; } + /// Builds the into a Rich Embed format. + /// The built embed object. public Embed Build() { _embed.Footer = Footer?.Build(); diff --git a/src/Discord.Net.Core/Entities/Messages/IAttachment.cs b/src/Discord.Net.Core/Entities/Messages/IAttachment.cs index b1eb67b5b..408153df1 100644 --- a/src/Discord.Net.Core/Entities/Messages/IAttachment.cs +++ b/src/Discord.Net.Core/Entities/Messages/IAttachment.cs @@ -1,6 +1,6 @@ namespace Discord { - /// Represents a Discord attachment object. + /// Represents a Discord attachment. public interface IAttachment { /// Gets the snowflake ID of the attachment. diff --git a/src/Discord.Net.Rest/Entities/Messages/Attachment.cs b/src/Discord.Net.Rest/Entities/Messages/Attachment.cs index f33380ce3..a51ac8e09 100644 --- a/src/Discord.Net.Rest/Entities/Messages/Attachment.cs +++ b/src/Discord.Net.Rest/Entities/Messages/Attachment.cs @@ -7,19 +7,19 @@ namespace Discord [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class Attachment : IAttachment { - /// + /// public ulong Id { get; } - /// + /// public string Filename { get; } - /// + /// public string Url { get; } - /// + /// public string ProxyUrl { get; } - /// + /// public int Size { get; } - /// + /// public int? Height { get; } - /// + /// public int? Width { get; } internal Attachment(ulong id, string filename, string url, string proxyUrl, int size, int? height, int? width) diff --git a/src/Discord.Net.WebSocket/Commands/ShardedCommandContext.cs b/src/Discord.Net.WebSocket/Commands/ShardedCommandContext.cs index a29c9bb70..f970c32fc 100644 --- a/src/Discord.Net.WebSocket/Commands/ShardedCommandContext.cs +++ b/src/Discord.Net.WebSocket/Commands/ShardedCommandContext.cs @@ -1,9 +1,11 @@ -using Discord.WebSocket; +using Discord.WebSocket; namespace Discord.Commands { + /// The sharded variant of , which may contain the client, user, guild, channel, and message. public class ShardedCommandContext : SocketCommandContext, ICommandContext { + /// Gets the that the command is executed with. public new DiscordShardedClient Client { get; } public ShardedCommandContext(DiscordShardedClient client, SocketUserMessage msg) @@ -12,10 +14,12 @@ namespace Discord.Commands Client = client; } + /// Gets the shard ID of the command context. private static int GetShardId(DiscordShardedClient client, IGuild guild) => guild == null ? 0 : client.GetShardIdFor(guild); //ICommandContext + /// IDiscordClient ICommandContext.Client => Client; } } diff --git a/src/Discord.Net.WebSocket/Commands/SocketCommandContext.cs b/src/Discord.Net.WebSocket/Commands/SocketCommandContext.cs index bac62e81b..29d78ab45 100644 --- a/src/Discord.Net.WebSocket/Commands/SocketCommandContext.cs +++ b/src/Discord.Net.WebSocket/Commands/SocketCommandContext.cs @@ -3,7 +3,6 @@ using Discord.WebSocket; namespace Discord.Commands { /// The WebSocket variant of , which may contain the client, user, guild, channel, and message. - /// public class SocketCommandContext : ICommandContext { /// Gets the that the command is executed with.