Resolve Issue #1188 (Allow Users to specify position when creating a …

…new channel) (#1196)

* Added ability to specify position when creating a channel

* Adjusted categories to include guildproperties and allow specifying position when creating channel categories

* fixed unimplemented methods (for CreateCategoryChannelAsync) and added appropriate documentation

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

@@ -474,12 +474,13 @@ public interface IGuild : IDeletable, ISnowflakeEntity
         ///     Creates a new channel category in this guild.
         /// </summary>
         /// <param name="name">The new name for the category.</param>
+        /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
         ///     A task that represents the asynchronous creation operation. The task result contains the newly created
         ///     category channel.
         /// </returns>
-        Task<ICategoryChannel> CreateCategoryAsync(string name, RequestOptions options = null);
+        Task<ICategoryChannel> CreateCategoryAsync(string name, Action<GuildChannelProperties> func = null, RequestOptions options = null);
 
         /// <summary>
         ///     Gets a collection of all the voice regions this guild can access.

src/Discord.Net.Rest/API/Rest/CreateGuildChannelParams.cs

@@ -12,6 +12,8 @@ internal class CreateGuildChannelParams
         public ChannelType Type { get; }
         [JsonProperty("parent_id")]
         public Optional<ulong?> CategoryId { get; set; }
+        [JsonProperty("position")]
+        public Optional<int> Position { get; set; }
 
         //Text channels
         [JsonProperty("topic")]

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

@@ -163,6 +163,7 @@ public static async Task<RestTextChannel> CreateTextChannelAsync(IGuild guild, B
                 CategoryId = props.CategoryId,
                 Topic = props.Topic,
                 IsNsfw = props.IsNsfw,
+                Position = props.Position
             };
             var model = await client.ApiClient.CreateGuildChannelAsync(guild.Id, args, options).ConfigureAwait(false);
             return RestTextChannel.Create(client, guild, model);
@@ -180,18 +181,26 @@ public static async Task<RestVoiceChannel> CreateVoiceChannelAsync(IGuild guild,
             {
                 CategoryId = props.CategoryId,
                 Bitrate = props.Bitrate,
-                UserLimit = props.UserLimit
+                UserLimit = props.UserLimit,
+                Position = props.Position
             };
             var model = await client.ApiClient.CreateGuildChannelAsync(guild.Id, args, options).ConfigureAwait(false);
             return RestVoiceChannel.Create(client, guild, model);
         }
         /// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
         public static async Task<RestCategoryChannel> CreateCategoryChannelAsync(IGuild guild, BaseDiscordClient client,
-            string name, RequestOptions options)
+            string name, RequestOptions options, Action<GuildChannelProperties> func = null)
         {
             if (name == null) throw new ArgumentNullException(paramName: nameof(name));
 
-            var args = new CreateGuildChannelParams(name, ChannelType.Category);
+            var props = new GuildChannelProperties();
+            func?.Invoke(props);
+
+            var args = new CreateGuildChannelParams(name, ChannelType.Category)
+            {
+                Position = props.Position
+            };
+
             var model = await client.ApiClient.CreateGuildChannelAsync(guild.Id, args, options).ConfigureAwait(false);
             return RestCategoryChannel.Create(client, guild, model);
         }

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

@@ -441,13 +441,14 @@ public Task<RestVoiceChannel> CreateVoiceChannelAsync(string name, Action<VoiceC
         ///     Creates a category channel with the provided name.
         /// </summary>
         /// <param name="name">The name of the new channel.</param>
+        /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
         /// <returns>
         ///     The created category channel.
         /// </returns>
-        public Task<RestCategoryChannel> CreateCategoryChannelAsync(string name, RequestOptions options = null)
-            => GuildHelper.CreateCategoryChannelAsync(this, Discord, name, options);
+        public Task<RestCategoryChannel> CreateCategoryChannelAsync(string name, Action<GuildChannelProperties> func = null, RequestOptions options = null)
+            => GuildHelper.CreateCategoryChannelAsync(this, Discord, name, options, func);
 
         /// <summary>
         ///     Gets a collection of all the voice regions this guild can access.
@@ -776,8 +777,8 @@ async Task<ITextChannel> IGuild.CreateTextChannelAsync(string name, Action<TextC
         async Task<IVoiceChannel> IGuild.CreateVoiceChannelAsync(string name, Action<VoiceChannelProperties> func, RequestOptions options)
             => await CreateVoiceChannelAsync(name, func, options).ConfigureAwait(false);
         /// <inheritdoc />
-        async Task<ICategoryChannel> IGuild.CreateCategoryAsync(string name, RequestOptions options)
-            => await CreateCategoryChannelAsync(name, options).ConfigureAwait(false);
+        async Task<ICategoryChannel> IGuild.CreateCategoryAsync(string name, Action<GuildChannelProperties> func, RequestOptions options)
+            => await CreateCategoryChannelAsync(name, func, options).ConfigureAwait(false);
 
         /// <inheritdoc />
         async Task<IReadOnlyCollection<IVoiceRegion>> IGuild.GetVoiceRegionsAsync(RequestOptions options)

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

@@ -561,14 +561,15 @@ public Task<RestVoiceChannel> CreateVoiceChannelAsync(string name, Action<VoiceC
         ///     Creates a new channel category in this guild.
         /// </summary>
         /// <param name="name">The new name for the category.</param>
+        /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
         /// <returns>
         ///     A task that represents the asynchronous creation operation. The task result contains the newly created
         ///     category channel.
         /// </returns>
-        public Task<RestCategoryChannel> CreateCategoryChannelAsync(string name, RequestOptions options = null)
-            => GuildHelper.CreateCategoryChannelAsync(this, Discord, name, options);
+        public Task<RestCategoryChannel> CreateCategoryChannelAsync(string name, Action<GuildChannelProperties> func = null, RequestOptions options = null)
+            => GuildHelper.CreateCategoryChannelAsync(this, Discord, name, options, func);
 
         internal SocketGuildChannel AddChannel(ClientState state, ChannelModel model)
         {
@@ -1069,8 +1070,8 @@ async Task<ITextChannel> IGuild.CreateTextChannelAsync(string name, Action<TextC
         async Task<IVoiceChannel> IGuild.CreateVoiceChannelAsync(string name, Action<VoiceChannelProperties> func, RequestOptions options)
             => await CreateVoiceChannelAsync(name, func, options).ConfigureAwait(false);
         /// <inheritdoc />
-        async Task<ICategoryChannel> IGuild.CreateCategoryAsync(string name, RequestOptions options)
-            => await CreateCategoryChannelAsync(name, options).ConfigureAwait(false);
+        async Task<ICategoryChannel> IGuild.CreateCategoryAsync(string name, Action<GuildChannelProperties> func, RequestOptions options)
+            => await CreateCategoryChannelAsync(name, func, options).ConfigureAwait(false);
 
         /// <inheritdoc />
         async Task<IReadOnlyCollection<IVoiceRegion>> IGuild.GetVoiceRegionsAsync(RequestOptions options)