Doc/Rationalize user/chat generic helpers

README.md

@@ -12,7 +12,7 @@ All the Telegram Client APIs (MTProto) are supported so you can do everything th
 
 This ReadMe is a **quick but important tutorial** to learn the fundamentals about this library. Please read it all.
 
->⚠️ This library relies on asynchronous C# programming (`async/await`) so make sure you are familiar with this advanced topic before proceeding.  
+>⚠️ This library requires understanding advanced C# techniques such as **asynchronous programming** or **subclass pattern matching**...  
 >If you are a beginner in C#, starting a project based on this library might not be a great idea.
 
 # How to use
@@ -85,7 +85,7 @@ Another simple approach is to pass `Environment.GetEnvironmentVariable` as the c
 *(undefined variables get the default `null` behavior)*.
 
 Finally, if you want to redirect the library logs to your logger instead of the Console, you can install a delegate in the `WTelegram.Helpers.Log` static property.
-Its `int` argument is the log severity, compatible with the [LogLevel enum](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.loglevel)
+Its `int` argument is the log severity, compatible with the [LogLevel enum](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.loglevel).
 
 # Alternative simplified configuration & login
 Since version 3.0.0, a new approach to login/configuration has been added. Some people might find it easier to deal with:
@@ -185,7 +185,8 @@ Required API parameters/fields can sometimes be set to 0 or `null` when unused (
 
 I've added several useful converters, implicit cast or helper properties to various API objects so that they are more easy to manipulate.
 
-Beyond the TL async methods, the Client class offers a few other methods to simplify the sending/receiving of files, medias or messages.
+Beyond the TL async methods, the Client class offers a few other methods to simplify the sending/receiving of files, medias or messages,
+as well as generic handling of chats/channels.
 
 This library works best with **.NET 5.0+** (faster, no dependencies) and is also available for **.NET Standard 2.0** (.NET Framework 4.6.1+ & .NET Core 2.0+) and **Xamarin/Mono.Android**
 
@@ -200,10 +201,10 @@ This library can be used for any Telegram scenarios including:
 It has been tested in a Console app, [in Windows Forms](https://github.com/wiz0u/WTelegramClient/raw/master/Examples/WinForms_app.zip),
 [in ASP.NET webservice](https://github.com/wiz0u/WTelegramClient/raw/master/Examples/ASPnet_webapp.zip), and in Xamarin/Android.  
 
-Please don't use this library for Spam or Scam. Respect Telegram [Terms of Service](https://telegram.org/tos)
+Don't use this library for Spam or Scam. Respect Telegram [Terms of Service](https://telegram.org/tos)
 as well as the [API Terms of Service](https://core.telegram.org/api/terms) or you might get banned from Telegram servers.
 
 Developers feedback is welcome in the Telegram support group [@WTelegramClient](https://t.me/WTelegramClient)  
 You can also check our [📖 Frequently Asked Questions](https://github.com/wiz0u/WTelegramClient/blob/master/FAQ.md) for more help and troubleshooting guide.
 
-If you like this library, please [consider a donation](http://t.me/WTelegramBot?start=donate).❤ This will help the project keep going.
+If you like this library, please [consider a donation](http://t.me/WTelegramBot?start=donate) ❤ This will help the project keep going.

src/Client.Helpers.cs

@@ -580,13 +580,19 @@ namespace WTelegram
 		}
 
 		private const string OnlyChatChannel = "This method works on Chat & Channel only";
-		public Task<UpdatesBase> AddChatUser(InputPeer peer, InputUserBase user, int fwd_limit = int.MaxValue) => peer switch
+		/// <summary>Generic helper: Adds a single user to a Chat or Channel		<para>See <a href="https://corefork.telegram.org/method/messages.addChatUser"/><br/> and <a href="https://corefork.telegram.org/method/channels.inviteToChannel"/></para>		<para>Possible <see cref="RpcException"/> codes: 400,403</para></summary>
+		/// <param name="peer">Chat/Channel</param>
+		/// <param name="user">User to be added</param>
+		public Task<UpdatesBase> AddChatUser(InputPeer peer, InputUserBase user) => peer switch
 		{
-			InputPeerChat chat => this.Messages_AddChatUser(chat.chat_id, user, fwd_limit),
+			InputPeerChat chat => this.Messages_AddChatUser(chat.chat_id, user, int.MaxValue),
 			InputPeerChannel channel => this.Channels_InviteToChannel(channel, new[] { user }),
 			_ => throw new ArgumentException(OnlyChatChannel),
 		};
 
+		/// <summary>Generic helper: Kick a user from a Chat or Channel [bots: ✓]		<para>See <a href="https://corefork.telegram.org/method/channels.editBanned"/><br/> and <a href="https://corefork.telegram.org/method/messages.deleteChatUser"/></para>		<para>Possible <see cref="RpcException"/> codes: 400,403</para></summary>
+		/// <param name="peer">Chat/Channel</param>
+		/// <param name="user">User to be removed</param>
 		public Task<UpdatesBase> DeleteChatUser(InputPeer peer, InputUser user) => peer switch
 		{
 			InputPeerChat chat => this.Messages_DeleteChatUser(chat.chat_id, user, true),
@@ -594,6 +600,8 @@ namespace WTelegram
 			_ => throw new ArgumentException(OnlyChatChannel),
 		};
 
+		/// <summary>Generic helper: Leave a Chat or Channel [bots: ✓]		<para>See <a href="https://corefork.telegram.org/method/messages.deleteChatUser"/><br/> and <a href="https://corefork.telegram.org/method/channels.leaveChannel"/></para>		<para>Possible <see cref="RpcException"/> codes: 400,403</para></summary>
+		/// <param name="peer">Chat/Channel to leave</param>
 		public Task<UpdatesBase> LeaveChat(InputPeer peer) => peer switch
 		{
 			InputPeerChat chat => this.Messages_DeleteChatUser(chat.chat_id, InputUser.Self, true),
@@ -601,6 +609,10 @@ namespace WTelegram
 			_ => throw new ArgumentException(OnlyChatChannel),
 		};
 
+		/// <summary>Generic helper: Make a user admin in a Chat or Channel		<para>See <a href="https://corefork.telegram.org/method/messages.editChatAdmin"/><br/> and <a href="https://corefork.telegram.org/method/channels.editAdmin"/> [bots: ✓]</para>		<para>Possible <see cref="RpcException"/> codes: 400,403,406</para></summary>
+		/// <param name="peer">Chat/Channel</param>
+		/// <param name="user">The user to make admin</param>
+		/// <param name="is_admin">Whether to make them admin</param>
 		public async Task<UpdatesBase> EditChatAdmin(InputPeer peer, InputUserBase user, bool is_admin)
 		{
 			switch (peer)
@@ -617,6 +629,9 @@ namespace WTelegram
 			}
 		}
 
+		/// <summary>Generic helper: Change the photo of a Chat or Channel [bots: ✓]		<para>See <a href="https://corefork.telegram.org/method/messages.editChatPhoto"/><br/> and <a href="https://corefork.telegram.org/method/channels.editPhoto"/></para>		<para>Possible <see cref="RpcException"/> codes: 400,403</para></summary>
+		/// <param name="peer">Chat/Channel</param>
+		/// <param name="photo">New photo</param>
 		public Task<UpdatesBase> EditChatPhoto(InputPeer peer, InputChatPhotoBase photo) => peer switch
 		{
 			InputPeerChat chat => this.Messages_EditChatPhoto(chat.chat_id, photo),
@@ -624,6 +639,9 @@ namespace WTelegram
 			_ => throw new ArgumentException(OnlyChatChannel),
 		};
 
+		/// <summary>Generic helper: Edit the name of a Chat or Channel [bots: ✓]		<para>See <a href="https://corefork.telegram.org/method/messages.editChatTitle"/><br/> and <a href="https://corefork.telegram.org/method/channels.editTitle"/></para>		<para>Possible <see cref="RpcException"/> codes: 400,403</para></summary>
+		/// <param name="peer">Chat/Channel</param>
+		/// <param name="title">New name</param>
 		public Task<UpdatesBase> EditChatTitle(InputPeer peer, string title) => peer switch
 		{
 			InputPeerChat chat => this.Messages_EditChatTitle(chat.chat_id, title),
@@ -631,6 +649,8 @@ namespace WTelegram
 			_ => throw new ArgumentException(OnlyChatChannel),
 		};
 
+		/// <summary>Get full info about a Chat or Channel [bots: ✓]		<para>See <a href="https://corefork.telegram.org/method/messages.getFullChat"/><br/> and <a href="https://corefork.telegram.org/method/channels.getFullChannel"/></para>		<para>Possible <see cref="RpcException"/> codes: 400,403,406</para></summary>
+		/// <param name="peer">Chat/Channel</param>
 		public Task<Messages_ChatFull> GetFullChat(InputPeer peer) => peer switch
 		{
 			InputPeerChat chat => this.Messages_GetFullChat(chat.chat_id),
@@ -638,6 +658,8 @@ namespace WTelegram
 			_ => throw new ArgumentException(OnlyChatChannel),
 		};
 
+		/// <summary>Generic helper: Delete a Chat or Channel		<para>See <a href="https://corefork.telegram.org/method/messages.deleteChat"/><br/> and <a href="https://corefork.telegram.org/method/channels.deleteChannel"/></para>		<para>Possible <see cref="RpcException"/> codes: 400,403,406</para></summary>
+		/// <param name="peer">Chat/Channel to delete</param>
 		public async Task<UpdatesBase> DeleteChat(InputPeer peer)
 		{
 			switch (peer)
@@ -653,20 +675,23 @@ namespace WTelegram
 			}
 		}
 
+		/// <summary>Generic helper: Get individual messages by IDs [bots: ✓]		<para>See <a href="https://corefork.telegram.org/method/messages.getMessages"/><br/> and <a href="https://corefork.telegram.org/method/channels.getMessages"/></para>		<para>Possible <see cref="RpcException"/> codes: 400</para></summary>
+		/// <param name="peer">User/Chat/Channel</param>
+		/// <param name="id">IDs of messages to get</param>
 		public Task<Messages_MessagesBase> GetMessages(InputPeer peer, params InputMessage[] id)
 			=> peer is InputPeerChannel channel ? this.Channels_GetMessages(channel, id) : this.Messages_GetMessages(id);
 
+		/// <summary>Generic helper: Delete messages by IDs [bots: ✓]<br/>Messages are deleted for all participants		<para>See <a href="https://corefork.telegram.org/method/messages.deleteMessages"/><br/> and <a href="https://corefork.telegram.org/method/channels.deleteMessages"/></para>		<para>Possible <see cref="RpcException"/> codes: 400,403</para></summary>
+		/// <param name="peer">User/Chat/Channel</param>
+		/// <param name="id">IDs of messages to delete</param>
 		public Task<Messages_AffectedMessages> DeleteMessages(InputPeer peer, params int[] id)
-			=> peer is InputPeerChannel channel ? this.Channels_DeleteMessages(channel, id) : this.Messages_DeleteMessages(id);
+			=> peer is InputPeerChannel channel ? this.Channels_DeleteMessages(channel, id) : this.Messages_DeleteMessages(id, true);
 
-		/// <summary>Marks message history as read.		<para>See <a href="https://corefork.telegram.org/method/messages.readHistory"/><br/> and <a href="https://corefork.telegram.org/method/channels.readHistory"/></para>		<para>Possible <see cref="RpcException"/> codes: 400 (<a href="https://corefork.telegram.org/method/messages.readHistory#possible-errors">details</a>)</para></summary>
+		/// <summary>Generic helper: Marks message history as read.		<para>See <a href="https://corefork.telegram.org/method/messages.readHistory"/><br/> and <a href="https://corefork.telegram.org/method/channels.readHistory"/></para>		<para>Possible <see cref="RpcException"/> codes: 400</para></summary>
-		/// <param name="peer">Target user, channel or group</param>
+		/// <param name="peer">User/Chat/Channel</param>
 		/// <param name="max_id">If a positive value is passed, only messages with identifiers less or equal than the given one will be marked read</param>
-		public async Task<bool> ReadHistory(InputPeer peer, int max_id = default) => peer switch
+		public async Task<bool> ReadHistory(InputPeer peer, int max_id = default)
-		{
+			=> peer is InputPeerChannel channel ? await this.Channels_ReadHistory(channel, max_id) : (await this.Messages_ReadHistory(peer, max_id)) != null;
-			InputPeerChannel channel => await this.Channels_ReadHistory(channel, max_id),
-			_ => (await this.Messages_ReadHistory(peer, max_id)) != null
-		};
 		#endregion
 	}
 }