From 6203c48c11be56bdb1acf2a20c41e96d89fa6e0a Mon Sep 17 00:00:00 2001 From: quin lynch Date: Fri, 28 May 2021 06:47:10 -0300 Subject: [PATCH] Added documentation for all the new classes --- .../Message Components/ActionRowComponent.cs | 7 + .../Message Components/ButtonComponent.cs | 25 +++ .../Message Components/ComponentBuilder.cs | 161 +++++++++++++++++- .../Message Components/MessageComponent.cs | 9 + .../SocketMessageComponent.cs | 10 +- .../SocketMessageComponentData.cs | 3 + 6 files changed, 213 insertions(+), 2 deletions(-) diff --git a/src/Discord.Net.Core/Entities/Interactions/Message Components/ActionRowComponent.cs b/src/Discord.Net.Core/Entities/Interactions/Message Components/ActionRowComponent.cs index fb6168218..c29ef44a2 100644 --- a/src/Discord.Net.Core/Entities/Interactions/Message Components/ActionRowComponent.cs +++ b/src/Discord.Net.Core/Entities/Interactions/Message Components/ActionRowComponent.cs @@ -7,10 +7,17 @@ using System.Threading.Tasks; namespace Discord { + /// + /// Represents a Row for child components to live in. + /// public class ActionRowComponent : IMessageComponent { + /// public ComponentType Type { get; } = ComponentType.ActionRow; + /// + /// The child components in this row. + /// public IReadOnlyCollection Components { get; internal set; } internal ActionRowComponent() { } diff --git a/src/Discord.Net.Core/Entities/Interactions/Message Components/ButtonComponent.cs b/src/Discord.Net.Core/Entities/Interactions/Message Components/ButtonComponent.cs index 973e24da5..aede74687 100644 --- a/src/Discord.Net.Core/Entities/Interactions/Message Components/ButtonComponent.cs +++ b/src/Discord.Net.Core/Entities/Interactions/Message Components/ButtonComponent.cs @@ -7,20 +7,45 @@ using System.Threading.Tasks; namespace Discord { + /// + /// Represents a Button. + /// public class ButtonComponent : IMessageComponent { + /// public ComponentType Type { get; } = ComponentType.Button; + /// + /// The of this button, example buttons with each style can be found Here. + /// public ButtonStyle Style { get; } + /// + /// The label of the button, this is the text that is shown. + /// public string Label { get; } + /// + /// A that will be displayed with this button. + /// public IEmote Emote { get; } + /// + /// A unique id that will be sent with a . This is how you know what button was pressed. + /// public string CustomId { get; } + /// + /// A URL for a button. + /// + /// + /// You cannot have a button with a URL and a CustomId. + /// public string Url { get; } + /// + /// Whether this button is disabled or not. + /// public bool Disabled { get; } internal ButtonComponent(ButtonStyle style, string label, IEmote emote, string customId, string url, bool disabled) diff --git a/src/Discord.Net.Core/Entities/Interactions/Message Components/ComponentBuilder.cs b/src/Discord.Net.Core/Entities/Interactions/Message Components/ComponentBuilder.cs index e4937a795..532e0b2e5 100644 --- a/src/Discord.Net.Core/Entities/Interactions/Message Components/ComponentBuilder.cs +++ b/src/Discord.Net.Core/Entities/Interactions/Message Components/ComponentBuilder.cs @@ -6,10 +6,19 @@ using System.Threading.Tasks; namespace Discord { + /// + /// Represents a builder for creating a . + /// public class ComponentBuilder { + /// + /// The max amount of rows a message can have. + /// public const int MaxActionRowCount = 5; + /// + /// Gets or sets the Action Rows for this Component Builder. + /// public List ActionRows { get => _actionRows; @@ -25,11 +34,22 @@ namespace Discord private List _actionRows { get; set; } + /// + /// Adds a button to the specified row. + /// + /// The label text for the newly added button. + /// The style of this newly added button. + /// A to be used with this button. + /// The custom id of the newly added button. + /// A URL to be used only if the is a Link. + /// Whether or not the newly created button is disabled. + /// The row the button should be placed on. + /// The current builder. public ComponentBuilder WithButton( string label, + string customId, ButtonStyle style = ButtonStyle.Primary, IEmote emote = null, - string customId = null, string url = null, bool disabled = false, int row = 0) @@ -45,9 +65,20 @@ namespace Discord return this.WithButton(button, row); } + /// + /// Adds a button to the first row. + /// + /// The button to add to the first row. + /// The current builder. public ComponentBuilder WithButton(ButtonBuilder button) => this.WithButton(button, 0); + /// + /// Adds a button to the specified row. + /// + /// The button to add. + /// The row to add the button. + /// The current builder. public ComponentBuilder WithButton(ButtonBuilder button, int row) { var builtButton = button.Build(); @@ -75,6 +106,10 @@ namespace Discord return this; } + /// + /// Builds this builder into a used to send your components. + /// + /// A that can be sent with public MessageComponent Build() { if (this._actionRows != null) @@ -84,9 +119,19 @@ namespace Discord } } + /// + /// Represents a class used to build Action rows. + /// public class ActionRowBuilder { + /// + /// The max amount of child components this row can hold. + /// public const int MaxChildCount = 5; + + /// + /// Gets or sets the components inside this row. + /// public List Components { get => _components; @@ -101,12 +146,22 @@ namespace Discord private List _components { get; set; } + /// + /// Adds a list of components to the current row. + /// + /// The list of components to add. + /// The current builder. public ActionRowBuilder WithComponents(List components) { this.Components = components; return this; } + /// + /// Adds a component at the end of the current row. + /// + /// The component to add. + /// The current builder. public ActionRowBuilder WithComponent(ButtonComponent component) { if (this.Components == null) @@ -117,6 +172,12 @@ namespace Discord return this; } + /// + /// Builds the current builder to a that can be used within a + /// + /// A that can be used within a + /// cannot be null. + /// There must be at least 1 component in a row. public ActionRowComponent Build() { if (this.Components == null) @@ -129,11 +190,24 @@ namespace Discord } } + /// + /// Represents a class used to build 's. + /// public class ButtonBuilder { + /// + /// The max length of a . + /// public const int MaxLabelLength = 80; + + /// + /// The max length of a . + /// public const int MaxCustomIdLength = 100; + /// + /// Gets or sets the label of the current button. + /// public string Label { get => _label; @@ -147,6 +221,9 @@ namespace Discord } } + /// + /// Gets or sets the custom id of the current button. + /// public string CustomId { get => _customId; @@ -159,15 +236,36 @@ namespace Discord } } + /// + /// Gets or sets the of the current button. + /// public ButtonStyle Style { get; set; } + + /// + /// Gets or sets the of the current button. + /// public IEmote Emote { get; set; } + + /// + /// Gets or sets the url of the current button. + /// public string Url { get; set; } + + /// + /// Gets or sets whether the current button is disabled. + /// public bool Disabled { get; set; } private string _label; private string _customId; + /// + /// Creates a button with the style. + /// + /// The label to use on the newly created link button. + /// The url for this link button to go to. + /// A builder with the newly created button. public static ButtonBuilder CreateLinkButton(string label, string url) { var builder = new ButtonBuilder() @@ -178,6 +276,12 @@ namespace Discord return builder; } + /// + /// Creates a button with the style. + /// + /// The label for this danger button. + /// The custom id for this danger button. + /// A builder with the newly created button. public static ButtonBuilder CreateDangerButton(string label, string customId) { var builder = new ButtonBuilder() @@ -188,6 +292,12 @@ namespace Discord return builder; } + /// + /// Creates a button with the style. + /// + /// The label for this primary button. + /// The custom id for this primary button. + /// A builder with the newly created button. public static ButtonBuilder CreatePrimaryButton(string label, string customId) { var builder = new ButtonBuilder() @@ -198,6 +308,12 @@ namespace Discord return builder; } + /// + /// Creates a button with the style. + /// + /// The label for this secondary button. + /// The custom id for this secondary button. + /// A builder with the newly created button. public static ButtonBuilder CreateSecondaryButton(string label, string customId) { var builder = new ButtonBuilder() @@ -208,6 +324,12 @@ namespace Discord return builder; } + /// + /// Creates a button with the style. + /// + /// The label for this success button. + /// The custom id for this success button. + /// A builder with the newly created button. public static ButtonBuilder CreateSuccessButton(string label, string customId) { var builder = new ButtonBuilder() @@ -218,41 +340,78 @@ namespace Discord return builder; } + /// + /// Sets the current buttons label to the specified text. + /// + /// The text for the label + /// The current builder. public ButtonBuilder WithLabel(string label) { this.Label = label; return this; } + /// + /// Sets the current buttons style. + /// + /// The style for this builders button. + /// The current builder. public ButtonBuilder WithStyle(ButtonStyle style) { this.Style = style; return this; } + /// + /// Sets the current buttons emote. + /// + /// The emote to use for the current button. + /// The current builder. public ButtonBuilder WithEmote(IEmote emote) { this.Emote = emote; return this; } + /// + /// Sets the current buttons url. + /// + /// The url to use for the current button. + /// The current builder. public ButtonBuilder WithUrl(string url) { this.Url = url; return this; } + /// + /// Sets the custom id of the current button. + /// + /// The id to use for the current button. + /// The current builder. public ButtonBuilder WithCustomId(string id) { this.CustomId = id; return this; } + + /// + /// Sets whether the current button is disabled. + /// + /// Whether the current button is disabled or not. + /// The current builder. public ButtonBuilder WithDisabled(bool disabled) { this.Disabled = disabled; return this; } + /// + /// Builds this builder into a to be used in a . + /// + /// A to be used in a . + /// A button cannot contain a URL and a CustomId. + /// A button must have an Emote or a label. public ButtonComponent Build() { if (string.IsNullOrEmpty(this.Label) && this.Emote == null) diff --git a/src/Discord.Net.Core/Entities/Interactions/Message Components/MessageComponent.cs b/src/Discord.Net.Core/Entities/Interactions/Message Components/MessageComponent.cs index 7356b8c5b..82df2550e 100644 --- a/src/Discord.Net.Core/Entities/Interactions/Message Components/MessageComponent.cs +++ b/src/Discord.Net.Core/Entities/Interactions/Message Components/MessageComponent.cs @@ -6,8 +6,14 @@ using System.Threading.Tasks; namespace Discord { + /// + /// Represents a component object used to send components with messages. + /// public class MessageComponent { + /// + /// The components to be used in a message. + /// public IReadOnlyCollection Components { get; } internal MessageComponent(List components) @@ -15,6 +21,9 @@ namespace Discord this.Components = components; } + /// + /// Returns a empty . + /// internal static MessageComponent Empty => new MessageComponent(new List()); } diff --git a/src/Discord.Net.WebSocket/Entities/Interaction/Message Components/SocketMessageComponent.cs b/src/Discord.Net.WebSocket/Entities/Interaction/Message Components/SocketMessageComponent.cs index 6e97f9edd..0b077fda5 100644 --- a/src/Discord.Net.WebSocket/Entities/Interaction/Message Components/SocketMessageComponent.cs +++ b/src/Discord.Net.WebSocket/Entities/Interaction/Message Components/SocketMessageComponent.cs @@ -10,10 +10,19 @@ using Discord.Rest; namespace Discord.WebSocket { + /// + /// Represents a Websocket-based interaction type for Message Components. + /// public class SocketMessageComponent : SocketInteraction { + /// + /// The data received with this interaction, contains the button that was clicked. + /// new public SocketMessageComponentData Data { get; } + /// + /// The message that contained the trigger for this interaction. + /// public SocketMessage Message { get; private set; } internal SocketMessageComponent(DiscordSocketClient client, Model model) @@ -72,7 +81,6 @@ namespace Discord.WebSocket /// /// Message content is too long, length must be less or equal to . /// The parameters provided were invalid or the token was invalid. - public override async Task RespondAsync(string text = null, bool isTTS = false, Embed embed = null, InteractionResponseType type = InteractionResponseType.ChannelMessageWithSource, bool ephemeral = false, AllowedMentions allowedMentions = null, RequestOptions options = null, MessageComponent component = null) { diff --git a/src/Discord.Net.WebSocket/Entities/Interaction/Message Components/SocketMessageComponentData.cs b/src/Discord.Net.WebSocket/Entities/Interaction/Message Components/SocketMessageComponentData.cs index fad959e1d..8477432c7 100644 --- a/src/Discord.Net.WebSocket/Entities/Interaction/Message Components/SocketMessageComponentData.cs +++ b/src/Discord.Net.WebSocket/Entities/Interaction/Message Components/SocketMessageComponentData.cs @@ -7,6 +7,9 @@ using Model = Discord.API.MessageComponentInteractionData; namespace Discord.WebSocket { + /// + /// Represents the data sent with a . + /// public class SocketMessageComponentData { ///