add inline docs

src/Discord.Net.Core/Entities/Guilds/IGuild.cs

@@ -1142,6 +1142,10 @@ namespace Discord
         /// <summary>
         ///     Gets this guilds application commands.
         /// </summary>
+        /// <param name="withLocalizations">
+        ///     Whether to include full localization dictionaries in the returned objects,
+        ///     instead of the localized name and description fields.
+        /// </param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
         ///     A task that represents the asynchronous get operation. The task result contains a read-only collection

src/Discord.Net.Core/Entities/Interactions/ApplicationCommandOption.cs

@@ -87,6 +87,10 @@ namespace Discord
         /// </summary>
         public List<ChannelType> ChannelTypes { get; set; }
 
+        /// <summary>
+        ///     Gets or sets the localization dictionary for the name field of this option.
+        /// </summary>
+        /// <exception cref="ArgumentException">Thrown when any of the dictionary keys is an invalid locale.</exception>
         public IDictionary<string, string> NameLocalizations
         {
             get => _nameLocalizations;
@@ -103,6 +107,10 @@ namespace Discord
             }
         }
 
+        /// <summary>
+        ///     Gets or sets the localization dictionary for the description field of this option.
+        /// </summary>
+        /// <exception cref="ArgumentException">Thrown when any of the dictionary keys is an invalid locale.</exception>
         public IDictionary<string, string> DescriptionLocalizations
         {
             get => _descriptionLocalizations;
@@ -115,7 +123,7 @@ namespace Discord
 
                     EnsureValidOptionDescription(description);
                 }
-                _nameLocalizations = value;
+                _descriptionLocalizations = value;
             }
         }
 

src/Discord.Net.Core/Entities/Interactions/ApplicationCommandOptionChoice.cs

@@ -46,6 +46,10 @@ namespace Discord
             }
         }
 
+        /// <summary>
+        ///     Gets or sets the localization dictionary for the name field of this choice.
+        /// </summary>
+        /// <exception cref="ArgumentException">Thrown when any of the dictionary keys is an invalid locale.</exception>
         public IDictionary<string, string> NameLocalizations
         {
             get => _nameLocalizations;

src/Discord.Net.Core/Entities/Interactions/ApplicationCommandProperties.cs

@@ -1,5 +1,9 @@
+using System;
 using System.Collections;
 using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Linq;
+using System.Text.RegularExpressions;
 
 namespace Discord
 {
@@ -8,6 +12,9 @@ namespace Discord
     /// </summary>
     public abstract class ApplicationCommandProperties
     {
+        private IReadOnlyDictionary<string, string> _nameLocalizations;
+        private IReadOnlyDictionary<string, string> _descriptionLocalizations;
+
         internal abstract ApplicationCommandType Type { get; }
 
         /// <summary>
@@ -20,9 +27,47 @@ namespace Discord
         /// </summary>
         public Optional<bool> IsDefaultPermission { get; set; }
 
-        public IDictionary<string, string>? NameLocalizations { get; set; }
+        /// <summary>
+        ///     Gets or sets the localization dictionary for the name field of this command.
+        /// </summary>
+        public IReadOnlyDictionary<string, string>? NameLocalizations
+        {
+            get => _nameLocalizations;
+            set
+            {
+                foreach (var (locale, name) in value)
+                {
+                    if(!Regex.IsMatch(locale, @"^\w{2}(?:-\w{2})?$"))
+                        throw new ArgumentException($"Invalid locale: {locale}", nameof(locale));
+
+                    Preconditions.AtLeast(name.Length, 1, nameof(name));
+                    Preconditions.AtMost(name.Length, SlashCommandBuilder.MaxNameLength, nameof(name));
+                    if (!Regex.IsMatch(name, @"^[\w-]{1,32}$"))
+                        throw new ArgumentException("Option name cannot contain any special characters or whitespaces!", nameof(name));
+                }
+                _nameLocalizations = value;
+            }
+        }
+
+        /// <summary>
+        ///     Gets or sets the localization dictionary for the description field of this command.
+        /// </summary>
+        public IReadOnlyDictionary<string, string>? DescriptionLocalizations
+        {
+            get => _descriptionLocalizations;
+            set
+            {
+                foreach (var (locale, description) in value)
+                {
+                    if(!Regex.IsMatch(locale, @"^\w{2}(?:-\w{2})?$"))
+                        throw new ArgumentException($"Invalid locale: {locale}", nameof(locale));
 
-        public IDictionary<string, string>? DescriptionLocalizations { get; set; }
+                    Preconditions.AtLeast(description.Length, 1, nameof(description));
+                    Preconditions.AtMost(description.Length, SlashCommandBuilder.MaxDescriptionLength, nameof(description));
+                }
+                _descriptionLocalizations = value;
+            }
+        }
 
         internal ApplicationCommandProperties() { }
     }

src/Discord.Net.Core/Entities/Interactions/ContextMenus/MessageCommandBuilder.cs

@@ -36,6 +36,9 @@ namespace Discord
         /// </summary>
         public bool IsDefaultPermission { get; set; } = true;
 
+        /// <summary>
+        ///     Gets the localization dictionary for the name field of this command.
+        /// </summary>
         public IReadOnlyDictionary<string, string> NameLocalizations => _nameLocalizations;
 
         private string _name;
@@ -82,6 +85,13 @@ namespace Discord
             return this;
         }
 
+        /// <summary>
+        ///     Sets the <see cref="NameLocalizations"/> collection.
+        /// </summary>
+        /// <param name="nameLocalizations">Localization dictionary for the name field of this command.</param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="nameLocalizations"/> is null.</exception>
+        /// <exception cref="ArgumentException">Thrown if any dictionary key is an invalid locale string.</exception>
         public MessageCommandBuilder WithNameLocalizations(IDictionary<string, string> nameLocalizations)
         {
             if (nameLocalizations is null)
@@ -99,6 +109,13 @@ namespace Discord
             return this;
         }
 
+        /// <summary>
+        ///     Adds a new entry to the <see cref="NameLocalizations"/> collection.
+        /// </summary>
+        /// <param name="locale">Locale of the entry.</param>
+        /// <param name="name">Localized string for the name field.</param>
+        /// <returns>The current builder.</returns>
+        /// <exception cref="ArgumentException">Thrown if <paramref name="locale"/> is an invalid locale string.</exception>
         public MessageCommandBuilder AddNameLocalization(string locale, string name)
         {
             if(!Regex.IsMatch(locale, @"^\w{2}(?:-\w{2})?$"))
@@ -112,7 +129,7 @@ namespace Discord
             return this;
         }
 
-        internal static void EnsureValidCommandName(string name)
+        private static void EnsureValidCommandName(string name)
         {
             Preconditions.NotNullOrEmpty(name, nameof(name));
             Preconditions.AtLeast(name.Length, 1, nameof(name));

src/Discord.Net.Core/Entities/Interactions/ContextMenus/UserCommandBuilder.cs

@@ -36,6 +36,9 @@ namespace Discord
         /// </summary>
         public bool IsDefaultPermission { get; set; } = true;
 
+        /// <summary>
+        ///     Gets the localization dictionary for the name field of this command.
+        /// </summary>
         public IReadOnlyDictionary<string, string> NameLocalizations => _nameLocalizations;
 
         private string _name;
@@ -80,6 +83,13 @@ namespace Discord
             return this;
         }
 
+        /// <summary>
+        ///     Sets the <see cref="NameLocalizations"/> collection.
+        /// </summary>
+        /// <param name="nameLocalizations">Localization dictionary for the name field of this command.</param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="nameLocalizations"/> is null.</exception>
+        /// <exception cref="ArgumentException">Thrown if any dictionary key is an invalid locale string.</exception>
         public UserCommandBuilder WithNameLocalizations(IDictionary<string, string> nameLocalizations)
         {
             if (nameLocalizations is null)
@@ -97,6 +107,13 @@ namespace Discord
             return this;
         }
 
+        /// <summary>
+        ///     Adds a new entry to the <see cref="NameLocalizations"/> collection.
+        /// </summary>
+        /// <param name="locale">Locale of the entry.</param>
+        /// <param name="name">Localized string for the name field.</param>
+        /// <returns>The current builder.</returns>
+        /// <exception cref="ArgumentException">Thrown if <paramref name="locale"/> is an invalid locale string.</exception>
         public UserCommandBuilder AddNameLocalization(string locale, string name)
         {
             if(!Regex.IsMatch(locale, @"^\w{2}(?:-\w{2})?$"))
@@ -110,7 +127,7 @@ namespace Discord
             return this;
         }
 
-        internal static void EnsureValidCommandName(string name)
+        private static void EnsureValidCommandName(string name)
         {
             Preconditions.NotNullOrEmpty(name, nameof(name));
             Preconditions.AtLeast(name.Length, 1, nameof(name));

src/Discord.Net.Core/Entities/Interactions/IApplicationCommand.cs

@@ -39,12 +39,30 @@ namespace Discord
         /// </summary>
         IReadOnlyCollection<IApplicationCommandOption> Options { get; }
 
+        /// <summary>
+        ///     Gets the localization dictionary for the name field of this command.
+        /// </summary>
         IReadOnlyDictionary<string, string>? NameLocalizations { get; }
 
+        /// <summary>
+        ///     Gets the localization dictionary for the description field of this command.
+        /// </summary>
         IReadOnlyDictionary<string, string>? DescriptionLocalizations { get; }
 
+        /// <summary>
+        ///     Gets the localized name of this command.
+        /// </summary>
+        /// <remarks>
+        ///     Only returned when the `withLocalizations` query parameter is set to true when requesting the command.
+        /// </remarks>
         string? NameLocalized { get; }
 
+        /// <summary>
+        ///     Gets the localized description of this command.
+        /// </summary>
+        /// <remarks>
+        ///     Only returned when the `withLocalizations` query parameter is set to true when requesting the command.
+        /// </remarks>
         string? DescriptionLocalized { get; }
 
         /// <summary>

src/Discord.Net.Core/Entities/Interactions/IApplicationCommandOption.cs

@@ -62,12 +62,30 @@ namespace Discord
         /// </summary>
         IReadOnlyCollection<ChannelType> ChannelTypes { get; }
 
+        /// <summary>
+        ///     Gets the localization dictionary for the name field of this command.
+        /// </summary>
         IReadOnlyDictionary<string, string>? NameLocalizations { get; }
 
+        /// <summary>
+        ///     Gets the localization dictionary for the description field of this command.
+        /// </summary>
         IReadOnlyDictionary<string, string>? DescriptionLocalizations { get; }
 
+        /// <summary>
+        ///     Gets the localized name of this command.
+        /// </summary>
+        /// <remarks>
+        ///     Only returned when the `withLocalizations` query parameter is set to true when requesting the command.
+        /// </remarks>
         string? NameLocalized { get; }
 
+        /// <summary>
+        ///     Gets the localized description of this command.
+        /// </summary>
+        /// <remarks>
+        ///     Only returned when the `withLocalizations` query parameter is set to true when requesting the command.
+        /// </remarks>
         string? DescriptionLocalized { get; }
     }
 }

src/Discord.Net.Core/Entities/Interactions/IApplicationCommandOptionChoice.cs

@@ -17,8 +17,17 @@ namespace Discord
         /// </summary>
         object Value { get; }
 
+        /// <summary>
+        ///     Gets the localization dictionary for the name field of this command.
+        /// </summary>
         IReadOnlyDictionary<string, string>? NameLocalizations { get; }
 
+        /// <summary>
+        ///     Gets the localized name of this command.
+        /// </summary>
+        /// <remarks>
+        ///     Only returned when the `withLocalizations` query parameter is set to true when requesting the command.
+        /// </remarks>
         string? NameLocalized { get; }
     }
 }

src/Discord.Net.Core/Entities/Interactions/SlashCommands/SlashCommandBuilder.cs

@@ -65,8 +65,14 @@ namespace Discord
             }
         }
 
+        /// <summary>
+        ///     Gets the localization dictionary for the name field of this command.
+        /// </summary>
         public IReadOnlyDictionary<string, string> NameLocalizations => _nameLocalizations;
 
+        /// <summary>
+        ///     Gets the localization dictionary for the description field of this command.
+        /// </summary>
         public IReadOnlyDictionary<string, string> DescriptionLocalizations => _descriptionLocalizations;
 
         /// <summary>
@@ -153,6 +159,8 @@ namespace Discord
         /// <param name="isAutocomplete">If this option is set to autocomplete.</param>
         /// <param name="options">The options of the option to add.</param>
         /// <param name="channelTypes">The allowed channel types for this option.</param>
+        /// <param name="nameLocalizations">Localization dictionary for the name field of this command.</param>
+        /// <param name="descriptionLocalizations">Localization dictionary for the description field of this command.</param>
         /// <param name="choices">The choices of this option.</param>
         /// <param name="minValue">The smallest number value the user can input.</param>
         /// <param name="maxValue">The largest number value the user can input.</param>
@@ -244,6 +252,13 @@ namespace Discord
             return this;
         }
 
+        /// <summary>
+        ///     Sets the <see cref="NameLocalizations"/> collection.
+        /// </summary>
+        /// <param name="nameLocalizations">Localization dictionary for the name field of this command.</param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="nameLocalizations"/> is null.</exception>
+        /// <exception cref="ArgumentException">Thrown if any dictionary key is an invalid locale string.</exception>
         public SlashCommandBuilder WithNameLocalizations(IDictionary<string, string> nameLocalizations)
         {
             if (nameLocalizations is null)
@@ -261,6 +276,13 @@ namespace Discord
             return this;
         }
 
+        /// <summary>
+        ///     Sets the <see cref="DescriptionLocalizations"/> collection.
+        /// </summary>
+        /// <param name="descriptionLocalizations">Localization dictionary for the name field of this command.</param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="descriptionLocalizations"/> is null.</exception>
+        /// <exception cref="ArgumentException">Thrown if any dictionary key is an invalid locale string.</exception>
         public SlashCommandBuilder WithDescriptionLocalizations(IDictionary<string, string> descriptionLocalizations)
         {
             if (descriptionLocalizations is null)
@@ -278,6 +300,13 @@ namespace Discord
             return this;
         }
 
+        /// <summary>
+        ///     Adds a new entry to the <see cref="NameLocalizations"/> collection.
+        /// </summary>
+        /// <param name="locale">Locale of the entry.</param>
+        /// <param name="name">Localized string for the name field.</param>
+        /// <returns>The current builder.</returns>
+        /// <exception cref="ArgumentException">Thrown if <paramref name="locale"/> is an invalid locale string.</exception>
         public SlashCommandBuilder AddNameLocalization(string locale, string name)
         {
             if(!Regex.IsMatch(locale, @"^\w{2}(?:-\w{2})?$"))
@@ -291,6 +320,13 @@ namespace Discord
             return this;
         }
 
+        /// <summary>
+        ///     Adds a new entry to the <see cref="Description"/> collection.
+        /// </summary>
+        /// <param name="locale">Locale of the entry.</param>
+        /// <param name="description">Localized string for the description field.</param>
+        /// <returns>The current builder.</returns>
+        /// <exception cref="ArgumentException">Thrown if <paramref name="locale"/> is an invalid locale string.</exception>
         public SlashCommandBuilder AddDescriptionLocalization(string locale, string description)
         {
             if(!Regex.IsMatch(locale, @"^\w{2}(?:-\w{2})?$"))
@@ -426,8 +462,14 @@ namespace Discord
         /// </summary>
         public List<ChannelType> ChannelTypes { get; set; }
 
+        /// <summary>
+        ///     Gets the localization dictionary for the name field of this command.
+        /// </summary>
         public IReadOnlyDictionary<string, string> NameLocalizations => _nameLocalizations;
 
+        /// <summary>
+        ///     Gets the localization dictionary for the description field of this command.
+        /// </summary>
         public IReadOnlyDictionary<string, string> DescriptionLocalizations => _descriptionLocalizations;
 
         /// <summary>
@@ -482,6 +524,8 @@ namespace Discord
         /// <param name="isAutocomplete">If this option supports autocomplete.</param>
         /// <param name="options">The options of the option to add.</param>
         /// <param name="channelTypes">The allowed channel types for this option.</param>
+        /// <param name="nameLocalizations">Localization dictionary for the description field of this command.</param>
+        /// <param name="descriptionLocalizations">Localization dictionary for the description field of this command.</param>
         /// <param name="choices">The choices of this option.</param>
         /// <param name="minValue">The smallest number value the user can input.</param>
         /// <param name="maxValue">The largest number value the user can input.</param>
@@ -556,6 +600,7 @@ namespace Discord
         /// </summary>
         /// <param name="name">The name of the choice.</param>
         /// <param name="value">The value of the choice.</param>
+        /// <param name="nameLocalizations">Localization dictionary for the description field of this command.</param>
         /// <returns>The current builder.</returns>
         public SlashCommandOptionBuilder AddChoice(string name, int value, IDictionary<string, string> nameLocalizations = null)
         {
@@ -567,6 +612,7 @@ namespace Discord
         /// </summary>
         /// <param name="name">The name of the choice.</param>
         /// <param name="value">The value of the choice.</param>
+        /// <param name="nameLocalizations">Localization dictionary for the description field of this command.</param>
         /// <returns>The current builder.</returns>
         public SlashCommandOptionBuilder AddChoice(string name, string value, IDictionary<string, string> nameLocalizations = null)
         {
@@ -578,6 +624,7 @@ namespace Discord
         /// </summary>
         /// <param name="name">The name of the choice.</param>
         /// <param name="value">The value of the choice.</param>
+        /// <param name="nameLocalizations">Localization dictionary for the description field of this command.</param>
         /// <returns>The current builder.</returns>
         public SlashCommandOptionBuilder AddChoice(string name, double value, IDictionary<string, string> nameLocalizations = null)
         {
@@ -589,6 +636,7 @@ namespace Discord
         /// </summary>
         /// <param name="name">The name of the choice.</param>
         /// <param name="value">The value of the choice.</param>
+        /// <param name="nameLocalizations">Localization dictionary for the description field of this command.</param>
         /// <returns>The current builder.</returns>
         public SlashCommandOptionBuilder AddChoice(string name, float value, IDictionary<string, string> nameLocalizations = null)
         {
@@ -600,6 +648,7 @@ namespace Discord
         /// </summary>
         /// <param name="name">The name of the choice.</param>
         /// <param name="value">The value of the choice.</param>
+        /// <param name="nameLocalizations">Localization dictionary for the description field of this command.</param>
         /// <returns>The current builder.</returns>
         public SlashCommandOptionBuilder AddChoice(string name, long value, IDictionary<string, string> nameLocalizations = null)
         {

src/Discord.Net.Interactions/InteractionService.cs

@@ -60,6 +60,11 @@ namespace Discord.Interactions
         public event Func<ModalCommandInfo, IInteractionContext, IResult, Task> ModalCommandExecuted { add { _modalCommandExecutedEvent.Add(value); } remove { _modalCommandExecutedEvent.Remove(value); } }
         internal readonly AsyncEvent<Func<ModalCommandInfo, IInteractionContext, IResult, Task>> _modalCommandExecutedEvent = new();
 
+        /// <summary>
+        ///     Get the <see cref="ILocalizationManager"/> used by this Interaction Service instance to localize strings.
+        /// </summary>
+        public ILocalizationManager LocalizationManager { get; set; }
+
         private readonly ConcurrentDictionary<Type, ModuleInfo> _typedModuleDefs;
         private readonly CommandMap<SlashCommandInfo> _slashCommandMap;
         private readonly ConcurrentDictionary<ApplicationCommandType, CommandMap<ContextCommandInfo>> _contextCommandMaps;
@@ -81,7 +86,6 @@ namespace Discord.Interactions
         internal readonly string _wildCardExp;
         internal readonly RunMode _runMode;
         internal readonly RestResponseCallback _restResponseCallback;
-        internal readonly ILocalizationManager _localizationManager;
 
         /// <summary>
         ///     Rest client to be used to register application commands.
@@ -181,7 +185,7 @@ namespace Discord.Interactions
             _enableAutocompleteHandlers = config.EnableAutocompleteHandlers;
             _autoServiceScopes = config.AutoServiceScopes;
             _restResponseCallback = config.RestResponseCallback;
-            _localizationManager = config.LocalizationManager;
+            LocalizationManager = config.LocalizationManager;
 
             _typeConverterMap = new TypeMap<TypeConverter, IApplicationCommandInteractionDataOption>(this, new ConcurrentDictionary<Type, TypeConverter>
                 {

src/Discord.Net.Interactions/Utilities/ApplicationCommandRestUtil.cs

@@ -10,7 +10,7 @@ namespace Discord.Interactions
         #region Parameters
         public static ApplicationCommandOptionProperties ToApplicationCommandOptionProps(this SlashCommandParameterInfo parameterInfo)
         {
-            var localizationManager = parameterInfo.Command.Module.CommandService._localizationManager;
+            var localizationManager = parameterInfo.Command.Module.CommandService.LocalizationManager;
             var parameterPath = parameterInfo.GetParameterPath();
 
             var props = new ApplicationCommandOptionProperties
@@ -43,7 +43,7 @@ namespace Discord.Interactions
         public static SlashCommandProperties ToApplicationCommandProps(this SlashCommandInfo commandInfo)
         {
             var commandPath = commandInfo.GetCommandPath();
-            var localizationManager = commandInfo.Module.CommandService._localizationManager;
+            var localizationManager = commandInfo.Module.CommandService.LocalizationManager;
 
             var props = new SlashCommandBuilder()
             {
@@ -64,7 +64,7 @@ namespace Discord.Interactions
 
         public static ApplicationCommandOptionProperties ToApplicationCommandOptionProps(this SlashCommandInfo commandInfo)
         {
-            var localizationManager = commandInfo.Module.CommandService._localizationManager;
+            var localizationManager = commandInfo.Module.CommandService.LocalizationManager;
             var commandPath = commandInfo.GetCommandPath();
 
             return new ApplicationCommandOptionProperties
@@ -82,7 +82,7 @@ namespace Discord.Interactions
 
         public static ApplicationCommandProperties ToApplicationCommandProps(this ContextCommandInfo commandInfo)
         {
-            var localizationManager = commandInfo.Module.CommandService._localizationManager;
+            var localizationManager = commandInfo.Module.CommandService.LocalizationManager;
             var commandPath = commandInfo.GetCommandPath();
 
             return commandInfo.CommandType switch
@@ -136,7 +136,7 @@ namespace Discord.Interactions
 
                 options.AddRange(moduleInfo.SubModules?.SelectMany(x => x.ParseSubModule(args, ignoreDontRegister)));
 
-                var localizationManager = moduleInfo.CommandService._localizationManager;
+                var localizationManager = moduleInfo.CommandService.LocalizationManager;
                 var modulePath = moduleInfo.GetModulePath();
 
                 var props = new SlashCommandBuilder
@@ -186,9 +186,9 @@ namespace Discord.Interactions
                     Description = moduleInfo.Description,
                     Type = ApplicationCommandOptionType.SubCommandGroup,
                     Options = options,
-                    NameLocalizations = moduleInfo.CommandService._localizationManager?.GetAllNames(moduleInfo.GetModulePath(), LocalizationTarget.Group)
+                    NameLocalizations = moduleInfo.CommandService.LocalizationManager?.GetAllNames(moduleInfo.GetModulePath(), LocalizationTarget.Group)
                         ?? ImmutableDictionary<string, string>.Empty,
-                    DescriptionLocalizations = moduleInfo.CommandService._localizationManager?.GetAllDescriptions(moduleInfo.GetModulePath(), LocalizationTarget.Group)
+                    DescriptionLocalizations = moduleInfo.CommandService.LocalizationManager?.GetAllDescriptions(moduleInfo.GetModulePath(), LocalizationTarget.Group)
                         ?? ImmutableDictionary<string, string>.Empty,
                 } };
         }

src/Discord.Net.Rest/DiscordRestApiClient.cs

@@ -8,6 +8,7 @@ using Newtonsoft.Json;
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
+using System.ComponentModel.Design;
 using System.Diagnostics;
 using System.Globalization;
 using System.IO;