From 9cd11d02d78c419b84e79c3ea06195c028b99e3c Mon Sep 17 00:00:00 2001 From: Temirkhan Myrzamadi Date: Wed, 22 Jan 2020 01:41:32 +0600 Subject: [PATCH] Fix the docs of the rest of requests --- Cargo.toml | 5 +- src/requests/all/add_sticker_to_set.rs | 14 +-- src/requests/all/answer_callback_query.rs | 4 +- src/requests/all/answer_inline_query.rs | 17 ++-- src/requests/all/answer_pre_checkout_query.rs | 5 +- src/requests/all/answer_shipping_query.rs | 5 +- src/requests/all/create_new_sticker_set.rs | 23 +++-- src/requests/all/delete_chat_sticker_set.rs | 7 +- src/requests/all/edit_message_caption.rs | 18 ++-- .../all/edit_message_live_location.rs | 25 ++++-- src/requests/all/edit_message_media.rs | 27 +++--- src/requests/all/edit_message_reply_markup.rs | 18 ++-- src/requests/all/edit_message_text.rs | 30 ++++--- src/requests/all/export_chat_invite_link.rs | 33 ++++--- src/requests/all/forward_message.rs | 24 ++--- src/requests/all/get_chat.rs | 9 +- src/requests/all/get_chat_administrators.rs | 18 ++-- src/requests/all/get_chat_member.rs | 12 +-- src/requests/all/get_chat_members_count.rs | 10 +-- src/requests/all/get_file.rs | 9 +- src/requests/all/get_game_high_scores.rs | 22 +++-- src/requests/all/get_me.rs | 6 +- src/requests/all/get_sticker_set.rs | 8 +- src/requests/all/get_updates.rs | 90 ++++++++++--------- src/requests/all/get_user_profile_photos.rs | 18 ++-- src/requests/all/get_webhook_info.rs | 11 ++- src/requests/all/kick_chat_member.rs | 29 +++--- src/requests/all/leave_chat.rs | 8 +- src/requests/all/pin_chat_message.rs | 25 +++--- src/requests/all/promote_chat_member.rs | 40 +++++---- src/requests/all/restrict_chat_member.rs | 27 +++--- src/requests/all/send_animation.rs | 74 ++++++++------- src/requests/all/send_audio.rs | 89 +++++++++++------- src/requests/all/send_chat_action.rs | 32 ++++--- src/requests/all/send_contact.rs | 33 +++---- src/requests/all/send_document.rs | 69 ++++++++------ src/requests/all/send_game.rs | 29 +++--- src/requests/all/send_invoice.rs | 88 ++++++++++-------- src/requests/all/send_location.rs | 37 ++++---- src/requests/all/send_media_group.rs | 22 ++--- src/requests/all/send_message.rs | 46 +++++----- src/requests/all/send_photo.rs | 55 ++++++++---- src/requests/all/send_poll.rs | 35 +++++--- src/requests/all/send_sticker.rs | 45 ++++++---- src/requests/all/send_venue.rs | 46 ++++++---- src/requests/all/send_video.rs | 86 +++++++++++------- src/requests/all/send_video_note.rs | 69 ++++++++------ src/requests/all/send_voice.rs | 65 +++++++++----- .../set_chat_administrator_custom_title.rs | 21 +++-- src/requests/all/set_chat_description.rs | 15 ++-- src/requests/all/set_chat_permissions.rs | 16 ++-- src/requests/all/set_chat_photo.rs | 17 ++-- src/requests/all/set_chat_sticker_set.rs | 17 ++-- src/requests/all/set_chat_title.rs | 16 ++-- src/requests/all/set_game_score.rs | 32 ++++--- .../all/set_sticker_position_in_set.rs | 9 +- src/requests/all/set_webhook.rs | 78 +++++++++------- .../all/stop_message_live_location.rs | 19 ++-- src/requests/all/stop_poll.rs | 19 ++-- src/requests/all/unban_chat_member.rs | 15 ++-- src/requests/all/unpin_chat_message.rs | 11 +-- src/requests/all/upload_sticker_file.rs | 20 +++-- 62 files changed, 1091 insertions(+), 731 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index ec037e6c..41f4e5c4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,12 +15,13 @@ tokio-util = { version = "0.2.0", features = ["full"] } reqwest = { version = "0.10", features = ["json", "stream", "native-tls-vendored"] } log = "0.4.8" bytes = "0.5.3" +mime = "0.3.16" derive_more = "0.99.2" thiserror = "1.0.9" async-trait = "0.1.22" +duang = "0.1.2" futures = "0.3.1" pin-project = "0.4.6" serde_with_macros = "1.0.1" -either = "1.5.3" -mime = "0.3.16" \ No newline at end of file +either = "1.5.3" \ No newline at end of file diff --git a/src/requests/all/add_sticker_to_set.rs b/src/requests/all/add_sticker_to_set.rs index 9463afd3..3862f337 100644 --- a/src/requests/all/add_sticker_to_set.rs +++ b/src/requests/all/add_sticker_to_set.rs @@ -85,12 +85,16 @@ impl<'a> AddStickerToSet<'a> { /// **Png** image with the sticker, must be up to 512 kilobytes in size, /// dimensions must not exceed 512px, and either width or height must be - /// exactly 512px. Pass a file_id as a String to send a file that already - /// exists on the Telegram servers, pass an HTTP URL as a String for - /// Telegram to get a file from the Internet, or upload a new one using - /// multipart/form-data. [More info on Sending Files »]. + /// exactly 512px. /// - /// [More info on Sending Files »]: https://core.telegram.org/bots/api#sending-files + /// Pass [`InputFile::File`] to send a file that exists on + /// the Telegram servers (recommended), pass an [`InputFile::Url`] for + /// Telegram to get a .webp file from the Internet, or upload a new one + /// using [`InputFile::FileId`]. [More info on Sending Files »]. + /// + /// [`InputFile::File`]: crate::types::InputFile::File + /// [`InputFile::Url`]: crate::types::InputFile::Url + /// [`InputFile::FileId`]: crate::types::InputFile::FileId pub fn png_sticker(mut self, val: InputFile) -> Self { self.png_sticker = val; self diff --git a/src/requests/all/answer_callback_query.rs b/src/requests/all/answer_callback_query.rs index 721c30f3..c9796c0d 100644 --- a/src/requests/all/answer_callback_query.rs +++ b/src/requests/all/answer_callback_query.rs @@ -8,7 +8,9 @@ use crate::{ }; /// Use this method to send answers to callback queries sent from [inline -/// keyboards]. The answer will be displayed to the user as a notification at +/// keyboards]. +/// +/// The answer will be displayed to the user as a notification at /// the top of the chat screen or as an alert. /// /// [The official docs](https://core.telegram.org/bots/api#answercallbackquery). diff --git a/src/requests/all/answer_inline_query.rs b/src/requests/all/answer_inline_query.rs index 8bceafc2..5be2d475 100644 --- a/src/requests/all/answer_inline_query.rs +++ b/src/requests/all/answer_inline_query.rs @@ -84,15 +84,19 @@ impl<'a> AnswerInlineQuery<'a> { } /// The maximum amount of time in seconds that the result of the inline - /// query may be cached on the server. Defaults to 300. + /// query may be cached on the server. + /// + /// Defaults to 300. pub fn cache_time(mut self, val: i32) -> Self { self.cache_time = Some(val); self } /// Pass `true`, if results may be cached on the server side only for the - /// user that sent the query. By default, results may be returned to any - /// user who sends the same query. + /// user that sent the query. + /// + /// By default, results may be returned to any user who sends the same + /// query. #[allow(clippy::wrong_self_convention)] pub fn is_personal(mut self, val: bool) -> Self { self.is_personal = Some(val); @@ -100,9 +104,10 @@ impl<'a> AnswerInlineQuery<'a> { } /// Pass the offset that a client should send in the next query with the - /// same text to receive more results. Pass an empty string if there are no - /// more results or if you don‘t support pagination. Offset length can’t - /// exceed 64 bytes. + /// same text to receive more results. + /// + /// Pass an empty string if there are no more results or if you don‘t + /// support pagination. Offset length can’t exceed 64 bytes. pub fn next_offset(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/answer_pre_checkout_query.rs b/src/requests/all/answer_pre_checkout_query.rs index eebcbc6a..bf370cb1 100644 --- a/src/requests/all/answer_pre_checkout_query.rs +++ b/src/requests/all/answer_pre_checkout_query.rs @@ -80,8 +80,9 @@ impl<'a> AnswerPreCheckoutQuery<'a> { /// explains the reason for failure to proceed with the checkout (e.g. /// "Sorry, somebody just bought the last of our amazing black T-shirts /// while you were busy filling out your payment details. Please choose a - /// different color or garment!"). Telegram will display this message to the - /// user. + /// different color or garment!"). + /// + /// Telegram will display this message to the user. pub fn error_message(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/answer_shipping_query.rs b/src/requests/all/answer_shipping_query.rs index 0991dbbb..f89a36f3 100644 --- a/src/requests/all/answer_shipping_query.rs +++ b/src/requests/all/answer_shipping_query.rs @@ -85,8 +85,9 @@ impl<'a> AnswerShippingQuery<'a> { /// Required if ok is `false`. Error message in human readable form that /// explains why it is impossible to complete the order (e.g. "Sorry, - /// delivery to your desired address is unavailable'). Telegram will display - /// this message to the user. + /// delivery to your desired address is unavailable'). + /// + /// Telegram will display this message to the user. pub fn error_message(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/create_new_sticker_set.rs b/src/requests/all/create_new_sticker_set.rs index 99c8004b..02b8a715 100644 --- a/src/requests/all/create_new_sticker_set.rs +++ b/src/requests/all/create_new_sticker_set.rs @@ -84,10 +84,11 @@ impl<'a> CreateNewStickerSet<'a> { } /// Short name of sticker set, to be used in `t.me/addstickers/` URLs (e.g., - /// animals). Can contain only english letters, digits and underscores. Must - /// begin with a letter, can't contain consecutive underscores and must end - /// in `_by_`. `` is case insensitive. 1-64 - /// characters. + /// animals). Can contain only english letters, digits and underscores. + /// + /// Must begin with a letter, can't contain consecutive underscores and must + /// end in `_by_`. `` is case insensitive. + /// 1-64 characters. pub fn name(mut self, val: T) -> Self where T: Into, @@ -107,12 +108,16 @@ impl<'a> CreateNewStickerSet<'a> { /// **Png** image with the sticker, must be up to 512 kilobytes in size, /// dimensions must not exceed 512px, and either width or height must be - /// exactly 512px. Pass a file_id as a String to send a file that already - /// exists on the Telegram servers, pass an HTTP URL as a String for - /// Telegram to get a file from the Internet, or upload a new one using - /// multipart/form-data. [More info on Sending Files »]. + /// exactly 512px. /// - /// [More info on Sending Files »]: https://core.telegram.org/bots/api#sending-files + /// Pass [`InputFile::File`] to send a file that exists on + /// the Telegram servers (recommended), pass an [`InputFile::Url`] for + /// Telegram to get a .webp file from the Internet, or upload a new one + /// using [`InputFile::FileId`]. [More info on Sending Files »]. + /// + /// [`InputFile::File`]: crate::types::InputFile::File + /// [`InputFile::Url`]: crate::types::InputFile::Url + /// [`InputFile::FileId`]: crate::types::InputFile::FileId pub fn png_sticker(mut self, val: InputFile) -> Self { self.png_sticker = val; self diff --git a/src/requests/all/delete_chat_sticker_set.rs b/src/requests/all/delete_chat_sticker_set.rs index a207dbfc..cfb1f026 100644 --- a/src/requests/all/delete_chat_sticker_set.rs +++ b/src/requests/all/delete_chat_sticker_set.rs @@ -7,9 +7,10 @@ use crate::{ Bot, }; -/// Use this method to delete a group sticker set from a supergroup. The bot -/// must be an administrator in the chat for this to work and must have the -/// appropriate admin rights. Use the field `can_set_sticker_set` optionally +/// Use this method to delete a group sticker set from a supergroup. +/// +/// The bot must be an administrator in the chat for this to work and must have +/// the appropriate admin rights. Use the field `can_set_sticker_set` optionally /// returned in [`Bot::get_chat`] requests to check if the bot can use this /// method. /// diff --git a/src/requests/all/edit_message_caption.rs b/src/requests/all/edit_message_caption.rs index 17c8b927..75a6b8c1 100644 --- a/src/requests/all/edit_message_caption.rs +++ b/src/requests/all/edit_message_caption.rs @@ -7,9 +7,10 @@ use crate::{ Bot, }; -/// Use this method to edit captions of messages. On success, if edited message -/// is sent by the bot, the edited [`Message`] is returned, otherwise [`True`] -/// is returned. +/// Use this method to edit captions of messages. +/// +/// On success, if edited message is sent by the bot, the edited [`Message`] is +/// returned, otherwise [`True`] is returned. /// /// [The official docs](https://core.telegram.org/bots/api#editmessagecaption). /// @@ -70,12 +71,13 @@ impl<'a> EditMessageCaption<'a> { self } - /// Send [Markdown] or [HTML], if you want Telegram apps to show [bold, - /// italic, fixed-width text or inline URLs] in the media caption. + /// Send [Markdown] or [HTML], if you want Telegram apps to show + /// [bold, italic, fixed-width text or inline URLs] in the media caption. /// - /// [Markdown]: https://core.telegram.org/bots/api#markdown-style - /// [HTML]: https://core.telegram.org/bots/api#html-style - /// [bold, italic, fixed-width text or inline URLs]: https://core.telegram.org/bots/api#formatting-options + /// [Markdown]: crate::types::ParseMode::Markdown + /// [HTML]: crate::types::ParseMode::HTML + /// [bold, italic, fixed-width text or inline URLs]: + /// crate::types::ParseMode pub fn parse_mode(mut self, val: ParseMode) -> Self { self.parse_mode = Some(val); self diff --git a/src/requests/all/edit_message_live_location.rs b/src/requests/all/edit_message_live_location.rs index 982c38de..1980e0bd 100644 --- a/src/requests/all/edit_message_live_location.rs +++ b/src/requests/all/edit_message_live_location.rs @@ -7,24 +7,26 @@ use crate::{ Bot, }; -/// Use this method to edit live location messages. A location can be edited -/// until its live_period expires or editing is explicitly disabled by a call to -/// stopMessageLiveLocation. On success, if the edited message was sent by the -/// bot, the edited Message is returned, otherwise True is returned. +/// Use this method to edit live location messages. +/// +/// A location can be edited until its live_period expires or editing is +/// explicitly disabled by a call to stopMessageLiveLocation. On success, if the +/// edited message was sent by the bot, the edited [`Message`] is returned, +/// otherwise [`True`] is returned. +/// +/// [The official docs](https://core.telegram.org/bots/api#editmessagelivelocation). +/// +/// [`Message`]: crate::types::Message +/// [`True`]: crate::types::True #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct EditMessageLiveLocation<'a> { #[serde(skip_serializing)] bot: &'a Bot, - #[serde(flatten)] chat_or_inline_message: ChatOrInlineMessage, - - /// Latitude of new location latitude: f32, - /// Longitude of new location longitude: f32, - /// A JSON-serialized object for a new inline keyboard. reply_markup: Option, } @@ -64,16 +66,21 @@ impl<'a> EditMessageLiveLocation<'a> { self } + /// Latitude of new location. pub fn latitude(mut self, val: f32) -> Self { self.latitude = val; self } + /// Longitude of new location. pub fn longitude(mut self, val: f32) -> Self { self.longitude = val; self } + /// A JSON-serialized object for a new [inline keyboard]. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating pub fn reply_markup(mut self, val: InlineKeyboardMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/edit_message_media.rs b/src/requests/all/edit_message_media.rs index 2c3cff90..7ca1b1bb 100644 --- a/src/requests/all/edit_message_media.rs +++ b/src/requests/all/edit_message_media.rs @@ -6,21 +6,24 @@ use crate::{ }; /// Use this method to edit animation, audio, document, photo, or video -/// messages. If a message is a part of a message album, then it can be edited -/// only to a photo or a video. Otherwise, message type can be changed -/// arbitrarily. When inline message is edited, new file can't be uploaded. Use -/// previously uploaded file via its file_id or specify a URL. On success, if -/// the edited message was sent by the bot, the edited Message is returned, -/// otherwise True is returned. +/// messages. +/// +/// If a message is a part of a message album, then it can be edited only to a +/// photo or a video. Otherwise, message type can be changed arbitrarily. When +/// inline message is edited, new file can't be uploaded. Use previously +/// uploaded file via its `file_id` or specify a URL. On success, if the edited +/// message was sent by the bot, the edited [`Message`] is returned, +/// otherwise [`True`] is returned. +/// +/// [The official docs](https://core.telegram.org/bots/api#editmessagemedia). +/// +/// [`Message`]: crate::types::Message +/// [`True`]: crate::types::True #[derive(Debug, Clone)] pub struct EditMessageMedia<'a> { bot: &'a Bot, - chat_or_inline_message: ChatOrInlineMessage, - - /// A JSON-serialized object for a new media content of the message media: InputMedia, - /// A JSON-serialized object for a new inline keyboard. reply_markup: Option, } @@ -82,11 +85,15 @@ impl<'a> EditMessageMedia<'a> { self } + /// A JSON-serialized object for a new media content of the message. pub fn media(mut self, val: InputMedia) -> Self { self.media = val; self } + /// A JSON-serialized object for a new [inline keyboard]. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating pub fn reply_markup(mut self, val: InlineKeyboardMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/edit_message_reply_markup.rs b/src/requests/all/edit_message_reply_markup.rs index 3ad4dff1..fc4b3d45 100644 --- a/src/requests/all/edit_message_reply_markup.rs +++ b/src/requests/all/edit_message_reply_markup.rs @@ -7,19 +7,22 @@ use crate::{ Bot, }; -/// Use this method to edit only the reply markup of messages. On success, if -/// edited message is sent by the bot, the edited Message is returned, otherwise -/// True is returned. +/// Use this method to edit only the reply markup of messages. +/// +/// On success, if edited message is sent by the bot, the edited [`Message`] is +/// returned, otherwise [`True`] is returned. +/// +/// [The official docs](https://core.telegram.org/bots/api#editmessagereplymarkup). +/// +/// [`Message`]: crate::types::Message +/// [`True`]: crate::types::True #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct EditMessageReplyMarkup<'a> { #[serde(skip_serializing)] bot: &'a Bot, - #[serde(flatten)] chat_or_inline_message: ChatOrInlineMessage, - - /// A JSON-serialized object for an inline keyboard. reply_markup: Option, } @@ -55,6 +58,9 @@ impl<'a> EditMessageReplyMarkup<'a> { self } + /// A JSON-serialized object for an [inline keyboard]. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating pub fn reply_markup(mut self, val: InlineKeyboardMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/edit_message_text.rs b/src/requests/all/edit_message_text.rs index 4b88fd58..5ed33bc4 100644 --- a/src/requests/all/edit_message_text.rs +++ b/src/requests/all/edit_message_text.rs @@ -7,26 +7,25 @@ use crate::{ Bot, }; -/// Use this method to edit text and game messages. On success, if edited -/// message is sent by the bot, the edited Message is returned, otherwise True -/// is returned. +/// Use this method to edit text and game messages. +/// +/// On success, if edited message is sent by the bot, the edited [`Message`] is +/// returned, otherwise [`True`] is returned. +/// +/// [The official docs](https://core.telegram.org/bots/api#editmessagetext). +/// +/// [`Message`]: crate::types::Message +/// [`True`]: crate::types::True #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct EditMessageText<'a> { #[serde(skip_serializing)] bot: &'a Bot, - #[serde(flatten)] chat_or_inline_message: ChatOrInlineMessage, - - /// New text of the message text: String, - /// Send Markdown or HTML, if you want Telegram apps to show bold, italic, - /// fixed-width text or inline URLs in your bot's message. parse_mode: Option, - /// Disables link previews for links in this message disable_web_page_preview: Option, - /// A JSON-serialized object for an inline keyboard. reply_markup: Option, } @@ -69,6 +68,7 @@ impl<'a> EditMessageText<'a> { self } + /// New text of the message. pub fn text(mut self, val: T) -> Self where T: Into, @@ -77,16 +77,26 @@ impl<'a> EditMessageText<'a> { self } + /// Send [Markdown] or [HTML], if you want Telegram apps to show [bold, + /// italic, fixed-width text or inline URLs] in your bot's message. + /// + /// [Markdown]: https://core.telegram.org/bots/api#markdown-style + /// [HTML]: https://core.telegram.org/bots/api#html-style + /// [bold, italic, fixed-width text or inline URLs]: https://core.telegram.org/bots/api#formatting-options pub fn parse_mode(mut self, val: ParseMode) -> Self { self.parse_mode = Some(val); self } + /// Disables link previews for links in this message. pub fn disable_web_page_preview(mut self, val: bool) -> Self { self.disable_web_page_preview = Some(val); self } + /// A JSON-serialized object for an [inline keyboard]. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating pub fn reply_markup(mut self, val: InlineKeyboardMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/export_chat_invite_link.rs b/src/requests/all/export_chat_invite_link.rs index 3cb49728..e12fbcab 100644 --- a/src/requests/all/export_chat_invite_link.rs +++ b/src/requests/all/export_chat_invite_link.rs @@ -8,23 +8,29 @@ use crate::{ }; /// Use this method to generate a new invite link for a chat; any previously -/// generated link is revoked. The bot must be an administrator in the chat for -/// this to work and must have the appropriate admin rights. Returns the new -/// invite link as String on success.Note: Each administrator in a chat -/// generates their own invite links. Bots can't use invite links generated by -/// other administrators. If you want your bot to work with invite links, it -/// will need to generate its own link using exportChatInviteLink – after this -/// the link will become available to the bot via the getChat method. If your -/// bot needs to generate a new invite link replacing its previous one, use -/// exportChatInviteLink again. +/// generated link is revoked. +/// +/// The bot must be an administrator in the chat for this to work and must have +/// the appropriate admin rights. +/// +/// ## Note +/// Each administrator in a chat generates their own invite links. Bots can't +/// use invite links generated by other administrators. If you want your bot to +/// work with invite links, it will need to generate its own link using +/// [`Bot::export_chat_invite_link`] – after this the link will become available +/// to the bot via the [`Bot::get_chat`] method. If your bot needs to generate a +/// new invite link replacing its previous one, use +/// [`Bot::export_chat_invite_link`] again. +/// +/// [The official docs](https://core.telegram.org/bots/api#exportchatinvitelink). +/// +/// [`Bot::export_chat_invite_link`]: crate::Bot::export_chat_invite_link +/// [`Bot::get_chat`]: crate::Bot::get_chat #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct ExportChatInviteLink<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, } @@ -32,6 +38,7 @@ pub struct ExportChatInviteLink<'a> { impl Request for ExportChatInviteLink<'_> { type Output = String; + /// Returns the new invite link as `String` on success. async fn send(&self) -> ResponseResult { network::request_json( self.bot.client(), @@ -52,6 +59,8 @@ impl<'a> ExportChatInviteLink<'a> { Self { bot, chat_id } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/forward_message.rs b/src/requests/all/forward_message.rs index dd27d1f9..50e688ef 100644 --- a/src/requests/all/forward_message.rs +++ b/src/requests/all/forward_message.rs @@ -7,24 +7,17 @@ use crate::{ Bot, }; -/// Use this method to forward messages of any kind. On success, the sent -/// Message is returned. +/// Use this method to forward messages of any kind. +/// +/// [`The official docs`](https://core.telegram.org/bots/api#forwardmessage). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct ForwardMessage<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Unique identifier for the chat where the original message was sent (or - /// channel username in the format @channelusername) from_chat_id: ChatId, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// Message identifier in the chat specified in from_chat_id message_id: i32, } @@ -65,6 +58,8 @@ impl<'a> ForwardMessage<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -73,6 +68,8 @@ impl<'a> ForwardMessage<'a> { self } + /// Unique identifier for the chat where the original message was sent (or + /// channel username in the format `@channelusername`). #[allow(clippy::wrong_self_convention)] pub fn from_chat_id(mut self, val: T) -> Self where @@ -82,11 +79,18 @@ impl<'a> ForwardMessage<'a> { self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// Message identifier in the chat specified in [`from_chat_id`]. + /// + /// [`from_chat_id`]: ForwardMessage::from_chat_id pub fn message_id(mut self, val: i32) -> Self { self.message_id = val; self diff --git a/src/requests/all/get_chat.rs b/src/requests/all/get_chat.rs index a131e0b6..2686ce62 100644 --- a/src/requests/all/get_chat.rs +++ b/src/requests/all/get_chat.rs @@ -9,15 +9,14 @@ use crate::{ /// Use this method to get up to date information about the chat (current name /// of the user for one-on-one conversations, current username of a user, group -/// or channel, etc.). Returns a Chat object on success. +/// or channel, etc.). +/// +/// [The official docs](https://core.telegram.org/bots/api#getchat). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct GetChat<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target - /// supergroup or channel (in the format @channelusername) chat_id: ChatId, } @@ -45,6 +44,8 @@ impl<'a> GetChat<'a> { Self { bot, chat_id } } + /// Unique identifier for the target chat or username of the target + /// supergroup or channel (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/get_chat_administrators.rs b/src/requests/all/get_chat_administrators.rs index f4012b91..fb9fe986 100644 --- a/src/requests/all/get_chat_administrators.rs +++ b/src/requests/all/get_chat_administrators.rs @@ -7,19 +7,17 @@ use crate::{ Bot, }; -/// Use this method to get a list of administrators in a chat. On success, -/// returns an Array of ChatMember objects that contains information about all -/// chat administrators except other bots. If the chat is a group or a -/// supergroup and no administrators were appointed, only the creator will be -/// returned. +/// Use this method to get a list of administrators in a chat. +/// +/// If the chat is a group or a supergroup and no administrators were appointed, +/// only the creator will be returned. +/// +/// [The official docs](https://core.telegram.org/bots/api#getchatadministrators). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct GetChatAdministrators<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target - /// supergroup or channel (in the format @channelusername) chat_id: ChatId, } @@ -27,6 +25,8 @@ pub struct GetChatAdministrators<'a> { impl Request for GetChatAdministrators<'_> { type Output = Vec; + /// On success, returns an array that contains information about all chat + /// administrators except other bots. async fn send(&self) -> ResponseResult> { network::request_json( self.bot.client(), @@ -47,6 +47,8 @@ impl<'a> GetChatAdministrators<'a> { Self { bot, chat_id } } + /// Unique identifier for the target chat or username of the target + /// supergroup or channel (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/get_chat_member.rs b/src/requests/all/get_chat_member.rs index 0f5d86c6..24b6d687 100644 --- a/src/requests/all/get_chat_member.rs +++ b/src/requests/all/get_chat_member.rs @@ -7,18 +7,15 @@ use crate::{ Bot, }; -/// Use this method to get information about a member of a chat. Returns a -/// ChatMember object on success. +/// Use this method to get information about a member of a chat. +/// +/// [The official docs](https://core.telegram.org/bots/api#getchatmember). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct GetChatMember<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target - /// supergroup or channel (in the format @channelusername) chat_id: ChatId, - /// Unique identifier of the target user user_id: i32, } @@ -50,6 +47,8 @@ impl<'a> GetChatMember<'a> { } } + /// Unique identifier for the target chat or username of the target + /// supergroup or channel (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -58,6 +57,7 @@ impl<'a> GetChatMember<'a> { self } + /// Unique identifier of the target user. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self diff --git a/src/requests/all/get_chat_members_count.rs b/src/requests/all/get_chat_members_count.rs index 60c9789d..7e912efd 100644 --- a/src/requests/all/get_chat_members_count.rs +++ b/src/requests/all/get_chat_members_count.rs @@ -7,16 +7,14 @@ use crate::{ Bot, }; -/// Use this method to get the number of members in a chat. Returns Int on -/// success. +/// Use this method to get the number of members in a chat. +/// +/// [The official docs](https://core.telegram.org/bots/api#getchatmemberscount). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct GetChatMembersCount<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target - /// supergroup or channel (in the format @channelusername) chat_id: ChatId, } @@ -44,6 +42,8 @@ impl<'a> GetChatMembersCount<'a> { Self { bot, chat_id } } + /// Unique identifier for the target chat or username of the target + /// supergroup or channel (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/get_file.rs b/src/requests/all/get_file.rs index 9fdde40a..bbef0af5 100644 --- a/src/requests/all/get_file.rs +++ b/src/requests/all/get_file.rs @@ -12,8 +12,6 @@ use crate::{ /// /// For the moment, bots can download files of up to `20MB` in size. /// -/// On success, a [`File`] object is returned. -/// /// The file can then be downloaded via the link /// `https://api.telegram.org/file/bot/`, where `` /// is taken from the response. It is guaranteed that the link will be valid @@ -24,6 +22,8 @@ use crate::{ /// type. You should save the file's MIME type and name (if available) when the /// [`File`] object is received. /// +/// [The official docs](https://core.telegram.org/bots/api#getfile). +/// /// [`File`]: crate::types::file /// [`GetFile`]: self::GetFile #[serde_with_macros::skip_serializing_none] @@ -31,9 +31,7 @@ use crate::{ pub struct GetFile<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// File identifier to get info about - pub file_id: String, + file_id: String, } #[async_trait::async_trait] @@ -62,6 +60,7 @@ impl<'a> GetFile<'a> { } } + /// File identifier to get info about. pub fn file_id(mut self, value: F) -> Self where F: Into, diff --git a/src/requests/all/get_game_high_scores.rs b/src/requests/all/get_game_high_scores.rs index aba2599a..5f331bb2 100644 --- a/src/requests/all/get_game_high_scores.rs +++ b/src/requests/all/get_game_high_scores.rs @@ -7,22 +7,25 @@ use crate::{ Bot, }; -/// Use this method to get data for high score tables. Will return the score of -/// the specified user and several of his neighbors in a game. On success, -/// returns an Array of GameHighScore objects.This method will currently return -/// scores for the target user, plus two of his closest neighbors on each side. -/// Will also return the top three users if the user and his neighbors are not -/// among them. Please note that this behavior is subject to change. +/// Use this method to get data for high score tables. +/// +/// Will return the score of the specified user and several of his neighbors in +/// a game. +/// +/// ## Note +/// This method will currently return scores for the target user, plus two of +/// his closest neighbors on each side. Will also return the top three users if +/// the user and his neighbors are not among them. Please note that this +/// behavior is subject to change. +/// +/// [The official docs](https://core.telegram.org/bots/api#getgamehighscores). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct GetGameHighScores<'a> { #[serde(skip_serializing)] bot: &'a Bot, - #[serde(flatten)] chat_or_inline_message: ChatOrInlineMessage, - - /// Target user id user_id: i32, } @@ -59,6 +62,7 @@ impl<'a> GetGameHighScores<'a> { self } + /// Target user id. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self diff --git a/src/requests/all/get_me.rs b/src/requests/all/get_me.rs index 9f9b4df4..27d4ed7a 100644 --- a/src/requests/all/get_me.rs +++ b/src/requests/all/get_me.rs @@ -6,10 +6,9 @@ use crate::{ }; use serde::Serialize; -/// A filter method for testing your bot's auth token. Requires no parameters. -/// Returns basic information about the bot in form of a [`User`] object. +/// A simple method for testing your bot's auth token. Requires no parameters. /// -/// [`User`]: crate::types::User +/// [The official docs](https://core.telegram.org/bots/api#getme). #[derive(Debug, Clone, Copy, Serialize)] pub struct GetMe<'a> { #[serde(skip_serializing)] @@ -20,6 +19,7 @@ pub struct GetMe<'a> { impl Request for GetMe<'_> { type Output = User; + /// Returns basic information about the bot. #[allow(clippy::trivially_copy_pass_by_ref)] async fn send(&self) -> ResponseResult { network::request_json( diff --git a/src/requests/all/get_sticker_set.rs b/src/requests/all/get_sticker_set.rs index 2c181cd0..1e73d605 100644 --- a/src/requests/all/get_sticker_set.rs +++ b/src/requests/all/get_sticker_set.rs @@ -7,15 +7,14 @@ use crate::{ Bot, }; -/// Use this method to get a sticker set. On success, a StickerSet object is -/// returned. +/// Use this method to get a sticker set. +/// +/// [The official docs](https://core.telegram.org/bots/api#getstickerset). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct GetStickerSet<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Name of the sticker set name: String, } @@ -43,6 +42,7 @@ impl<'a> GetStickerSet<'a> { Self { bot, name } } + /// Name of the sticker set. pub fn name(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/get_updates.rs b/src/requests/all/get_updates.rs index 8a42942b..4b6e37f4 100644 --- a/src/requests/all/get_updates.rs +++ b/src/requests/all/get_updates.rs @@ -8,61 +8,24 @@ use crate::{ }; /// Use this method to receive incoming updates using long polling ([wiki]). -/// An array ([`Vec`]) of [`Update`]s is returned. /// /// **Notes:** /// 1. This method will not work if an outgoing webhook is set up. /// 2. In order to avoid getting duplicate updates, /// recalculate offset after each server response. /// +/// [The official docs](https://core.telegram.org/bots/api#getupdates). +/// /// [wiki]: https://en.wikipedia.org/wiki/Push_technology#Long_polling -/// [Update]: crate::types::Update -/// [Vec]: std::alloc::Vec #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct GetUpdates<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Identifier of the first update to be returned. Must be greater by one - /// than the highest among the identifiers of previously received updates. - /// By default, updates starting with the earliest unconfirmed update are - /// returned. An update is considered confirmed as soon as [`GetUpdates`] - /// is called with an [`offset`] higher than its [`id`]. The negative - /// offset can be specified to retrieve updates starting from `-offset` - /// update from the end of the updates queue. All previous updates will - /// forgotten. - /// - /// [`GetUpdates`]: self::GetUpdates - /// [`offset`]: self::GetUpdates::offset - /// [`id`]: crate::types::Update::id - pub offset: Option, - /// Limits the number of updates to be retrieved. - /// Values between `1`—`100` are accepted. Defaults to `100`. - pub limit: Option, - /// Timeout in seconds for long polling. Defaults to `0`, - /// i.e. usual short polling. Should be positive, short polling should be - /// used for testing purposes only. - pub timeout: Option, - /// List the types of updates you want your bot to receive. - /// For example, specify [[`Message`], [`EditedChannelPost`], - /// [`CallbackQuery`]] to only receive updates of these types. - /// See [`AllowedUpdate`] for a complete list of available update types. - /// - /// Specify an empty list to receive all updates regardless of type - /// (default). If not specified, the previous setting will be used. - /// - /// **Note:** - /// This parameter doesn't affect updates created before the call to the - /// [`GetUpdates`], so unwanted updates may be received for a short period - /// of time. - /// - /// [`Message`]: self::AllowedUpdate::Message - /// [`EditedChannelPost`]: self::AllowedUpdate::EditedChannelPost - /// [`CallbackQuery`]: self::AllowedUpdate::CallbackQuery - /// [`AllowedUpdate`]: self::AllowedUpdate - /// [`GetUpdates`]: self::GetUpdates - pub allowed_updates: Option>, + pub(crate) offset: Option, + pub(crate) limit: Option, + pub(crate) timeout: Option, + pub(crate) allowed_updates: Option>, } #[async_trait::async_trait] @@ -91,24 +54,63 @@ impl<'a> GetUpdates<'a> { } } + /// Identifier of the first update to be returned. + /// + /// Must be greater by one than the highest among the identifiers of + /// previously received updates. By default, updates starting with the + /// earliest unconfirmed update are returned. An update is considered + /// confirmed as soon as [`GetUpdates`] is called with an [`offset`] + /// higher than its [`id`]. The negative offset can be specified to + /// retrieve updates starting from `-offset` update from the end of the + /// updates queue. All previous updates will forgotten. + /// + /// [`GetUpdates`]: self::GetUpdates + /// [`offset`]: self::GetUpdates::offset + /// [`id`]: crate::types::Update::id pub fn offset(mut self, value: i32) -> Self { self.offset = Some(value); self } + /// Limits the number of updates to be retrieved. + /// + /// Values between `1`—`100` are accepted. Defaults to `100`. pub fn limit(mut self, value: u8) -> Self { self.limit = Some(value); self } + /// Timeout in seconds for long polling. + /// + /// Defaults to `0`, i.e. usual short polling. Should be positive, short + /// polling should be used for testing purposes only. pub fn timeout(mut self, value: u32) -> Self { self.timeout = Some(value); self } + /// List the types of updates you want your bot to receive. + /// + /// For example, specify [[`Message`], [`EditedChannelPost`], + /// [`CallbackQuery`]] to only receive updates of these types. + /// See [`AllowedUpdate`] for a complete list of available update types. + /// + /// Specify an empty list to receive all updates regardless of type + /// (default). If not specified, the previous setting will be used. + /// + /// **Note:** + /// This parameter doesn't affect updates created before the call to the + /// [`Bot::get_updates`], so unwanted updates may be received for a short + /// period of time. + /// + /// [`Message`]: self::AllowedUpdate::Message + /// [`EditedChannelPost`]: self::AllowedUpdate::EditedChannelPost + /// [`CallbackQuery`]: self::AllowedUpdate::CallbackQuery + /// [`AllowedUpdate`]: self::AllowedUpdate + /// [`Bot::get_updates`]: crate::Bot::get_updates pub fn allowed_updates(mut self, value: T) -> Self where - T: Into>, // TODO: into or other trait? + T: Into>, { self.allowed_updates = Some(value.into()); self diff --git a/src/requests/all/get_user_profile_photos.rs b/src/requests/all/get_user_profile_photos.rs index 1a50e617..bb2d2889 100644 --- a/src/requests/all/get_user_profile_photos.rs +++ b/src/requests/all/get_user_profile_photos.rs @@ -7,21 +7,16 @@ use crate::{ Bot, }; -/// Use this method to get a list of profile pictures for a user. Returns a -/// UserProfilePhotos object. +/// Use this method to get a list of profile pictures for a user. +/// +/// [The official docs](https://core.telegram.org/bots/api#getuserprofilephotos). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct GetUserProfilePhotos<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier of the target user user_id: i32, - /// Sequential number of the first photo to be returned. By default, all - /// photos are returned. offset: Option, - /// Limits the number of photos to be retrieved. Values between 1—100 are - /// accepted. Defaults to 100. limit: Option, } @@ -50,16 +45,23 @@ impl<'a> GetUserProfilePhotos<'a> { } } + /// Unique identifier of the target user. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self } + /// Sequential number of the first photo to be returned. By default, all + /// photos are returned. pub fn offset(mut self, val: i32) -> Self { self.offset = Some(val); self } + /// Limits the number of photos to be retrieved. Values between 1—100 are + /// accepted. + /// + /// Defaults to 100. pub fn limit(mut self, val: i32) -> Self { self.limit = Some(val); self diff --git a/src/requests/all/get_webhook_info.rs b/src/requests/all/get_webhook_info.rs index 8d5ef965..304c0c21 100644 --- a/src/requests/all/get_webhook_info.rs +++ b/src/requests/all/get_webhook_info.rs @@ -7,9 +7,14 @@ use crate::{ Bot, }; -/// Use this method to get current webhook status. Requires no parameters. On -/// success, returns a WebhookInfo object. If the bot is using getUpdates, will -/// return an object with the url field empty. +/// Use this method to get current webhook status. +/// +/// If the bot is using [`Bot::get_updates`], will return an object with the url +/// field empty. +/// +/// [The official docs](https://core.telegram.org/bots/api#getwebhookinfo). +/// +/// [`Bot::get_updates`]: crate::Bot::get_updates #[derive(Debug, Clone, Serialize)] pub struct GetWebhookInfo<'a> { #[serde(skip_serializing)] diff --git a/src/requests/all/kick_chat_member.rs b/src/requests/all/kick_chat_member.rs index db99a1f1..c3bed716 100644 --- a/src/requests/all/kick_chat_member.rs +++ b/src/requests/all/kick_chat_member.rs @@ -7,25 +7,23 @@ use crate::{ Bot, }; -/// Use this method to kick a user from a group, a supergroup or a channel. In -/// the case of supergroups and channels, the user will not be able to return to -/// the group on their own using invite links, etc., unless unbanned first. The -/// bot must be an administrator in the chat for this to work and must have the -/// appropriate admin rights. Returns True on success. +/// Use this method to kick a user from a group, a supergroup or a channel. +/// +/// In the case of supergroups and channels, the user will not be able to return +/// to the group on their own using invite links, etc., unless [unbanned] first. +/// The bot must be an administrator in the chat for this to work and must have +/// the appropriate admin rights. +/// +/// [The official docs](https://core.telegram.org/bots/api#kickchatmember). +/// +/// [unbanned]: crate::Bot::unban_chat_member #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct KickChatMember<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target group or username of the target - /// supergroup or channel (in the format @channelusername) chat_id: ChatId, - /// Unique identifier of the target user user_id: i32, - /// Date when the user will be unbanned, unix time. If user is banned for - /// more than 366 days or less than 30 seconds from the current time they - /// are considered to be banned forever until_date: Option, } @@ -58,6 +56,8 @@ impl<'a> KickChatMember<'a> { } } + /// Unique identifier for the target group or username of the target + /// supergroup or channel (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -66,11 +66,16 @@ impl<'a> KickChatMember<'a> { self } + /// Unique identifier of the target user. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self } + /// Date when the user will be unbanned, unix time. + /// + /// If user is banned for more than 366 days or less than 30 seconds from + /// the current time they are considered to be banned forever. pub fn until_date(mut self, val: i32) -> Self { self.until_date = Some(val); self diff --git a/src/requests/all/leave_chat.rs b/src/requests/all/leave_chat.rs index ea8f1a56..d656436a 100644 --- a/src/requests/all/leave_chat.rs +++ b/src/requests/all/leave_chat.rs @@ -8,15 +8,13 @@ use crate::{ }; /// Use this method for your bot to leave a group, supergroup or channel. -/// Returns True on success. +/// +/// [The official docs](https://core.telegram.org/bots/api#leavechat). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct LeaveChat<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target - /// supergroup or channel (in the format @channelusername) chat_id: ChatId, } @@ -44,6 +42,8 @@ impl<'a> LeaveChat<'a> { Self { bot, chat_id } } + /// Unique identifier for the target chat or username of the target + /// supergroup or channel (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/pin_chat_message.rs b/src/requests/all/pin_chat_message.rs index fe0ed246..6d5a14f7 100644 --- a/src/requests/all/pin_chat_message.rs +++ b/src/requests/all/pin_chat_message.rs @@ -7,24 +7,20 @@ use crate::{ Bot, }; -/// Use this method to pin a message in a group, a supergroup, or a channel. The -/// bot must be an administrator in the chat for this to work and must have the -/// ‘can_pin_messages’ admin right in the supergroup or ‘can_edit_messages’ -/// admin right in the channel. Returns True on success. +/// Use this method to pin a message in a group, a supergroup, or a channel. +/// +/// The bot must be an administrator in the chat for this to work and must have +/// the `can_pin_messages` admin right in the supergroup or `can_edit_messages` +/// admin right in the channel. +/// +/// [The official docs](https://core.telegram.org/bots/api#pinchatmessage). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct PinChatMessage<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Identifier of a message to pin message_id: i32, - /// Pass True, if it is not necessary to send a notification to all chat - /// members about the new pinned message. Notifications are always disabled - /// in channels. disable_notification: Option, } @@ -57,6 +53,8 @@ impl<'a> PinChatMessage<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -65,11 +63,16 @@ impl<'a> PinChatMessage<'a> { self } + /// Identifier of a message to pin. pub fn message_id(mut self, val: i32) -> Self { self.message_id = val; self } + /// Pass `true`, if it is not necessary to send a notification to all chat + /// members about the new pinned message. + /// + /// Notifications are always disabled in channels. pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self diff --git a/src/requests/all/promote_chat_member.rs b/src/requests/all/promote_chat_member.rs index 49e497bb..8a8a96f9 100644 --- a/src/requests/all/promote_chat_member.rs +++ b/src/requests/all/promote_chat_member.rs @@ -8,40 +8,26 @@ use crate::{ }; /// Use this method to promote or demote a user in a supergroup or a channel. +/// /// The bot must be an administrator in the chat for this to work and must have /// the appropriate admin rights. Pass False for all boolean parameters to -/// demote a user. Returns True on success. +/// demote a user. +/// +/// [The official docs](https://core.telegram.org/bots/api#promotechatmember). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct PromoteChatMember<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Unique identifier of the target user user_id: i32, - /// Pass True, if the administrator can change chat title, photo and other - /// settings can_change_info: Option, - /// Pass True, if the administrator can create channel posts, channels only can_post_messages: Option, - /// Pass True, if the administrator can edit messages of other users and - /// can pin messages, channels only can_edit_messages: Option, - /// Pass True, if the administrator can delete messages of other users can_delete_messages: Option, - /// Pass True, if the administrator can invite new users to the chat can_invite_users: Option, - /// Pass True, if the administrator can restrict, ban or unban chat members can_restrict_members: Option, - /// Pass True, if the administrator can pin messages, supergroups only can_pin_messages: Option, - /// Pass True, if the administrator can add new administrators with a - /// subset of his own privileges or demote administrators that he has - /// promoted, directly or indirectly (promoted by administrators that were - /// appointed by him) can_promote_members: Option, } @@ -81,6 +67,8 @@ impl<'a> PromoteChatMember<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -89,46 +77,62 @@ impl<'a> PromoteChatMember<'a> { self } + /// Unique identifier of the target user. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self } + /// Pass `true`, if the administrator can change chat title, photo and other + /// settings. pub fn can_change_info(mut self, val: bool) -> Self { self.can_change_info = Some(val); self } + /// Pass `true`, if the administrator can create channel posts, channels + /// only. pub fn can_post_messages(mut self, val: bool) -> Self { self.can_post_messages = Some(val); self } + /// Pass `true`, if the administrator can edit messages of other users and + /// can pin messages, channels only. pub fn can_edit_messages(mut self, val: bool) -> Self { self.can_edit_messages = Some(val); self } + /// Pass `true`, if the administrator can delete messages of other users. pub fn can_delete_messages(mut self, val: bool) -> Self { self.can_delete_messages = Some(val); self } + /// Pass `true`, if the administrator can invite new users to the chat. pub fn can_invite_users(mut self, val: bool) -> Self { self.can_invite_users = Some(val); self } + /// Pass `true`, if the administrator can restrict, ban or unban chat + /// members. pub fn can_restrict_members(mut self, val: bool) -> Self { self.can_restrict_members = Some(val); self } + /// Pass `true`, if the administrator can pin messages, supergroups only. pub fn can_pin_messages(mut self, val: bool) -> Self { self.can_pin_messages = Some(val); self } + /// Pass `true`, if the administrator can add new administrators with a + /// subset of his own privileges or demote administrators that he has + /// promoted, directly or indirectly (promoted by administrators that were + /// appointed by him). pub fn can_promote_members(mut self, val: bool) -> Self { self.can_promote_members = Some(val); self diff --git a/src/requests/all/restrict_chat_member.rs b/src/requests/all/restrict_chat_member.rs index abcedb30..d8059528 100644 --- a/src/requests/all/restrict_chat_member.rs +++ b/src/requests/all/restrict_chat_member.rs @@ -7,26 +7,21 @@ use crate::{ Bot, }; -/// Use this method to restrict a user in a supergroup. The bot must be an -/// administrator in the supergroup for this to work and must have the -/// appropriate admin rights. Pass True for all permissions to lift restrictions -/// from a user. Returns True on success. +/// Use this method to restrict a user in a supergroup. +/// +/// The bot must be an administrator in the supergroup for this to work and must +/// have the appropriate admin rights. Pass `true` for all permissions to lift +/// restrictions from a user. +/// +/// [The official docs](https://core.telegram.org/bots/api#restrictchatmember). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct RestrictChatMember<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target - /// supergroup (in the format @supergroupusername) chat_id: ChatId, - /// Unique identifier of the target user user_id: i32, - /// New user permissions permissions: ChatPermissions, - /// Date when restrictions will be lifted for the user, unix time. If user - /// is restricted for more than 366 days or less than 30 seconds from the - /// current time, they are considered to be restricted forever until_date: Option, } @@ -65,6 +60,8 @@ impl<'a> RestrictChatMember<'a> { } } + /// Unique identifier for the target chat or username of the target + /// supergroup (in the format `@supergroupusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -73,16 +70,22 @@ impl<'a> RestrictChatMember<'a> { self } + /// Unique identifier of the target user. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self } + /// New user permissions. pub fn permissions(mut self, val: ChatPermissions) -> Self { self.permissions = val; self } + /// Date when restrictions will be lifted for the user, unix time. + /// + /// If user is restricted for more than 366 days or less than 30 seconds + /// from the current time, they are considered to be restricted forever. pub fn until_date(mut self, val: i32) -> Self { self.until_date = Some(val); self diff --git a/src/requests/all/send_animation.rs b/src/requests/all/send_animation.rs index 9a9548f7..66d5314d 100644 --- a/src/requests/all/send_animation.rs +++ b/src/requests/all/send_animation.rs @@ -8,52 +8,23 @@ use crate::{ /// Use this method to send animation files (GIF or H.264/MPEG-4 AVC video /// without sound). /// -/// On success, the sent Message is returned. -/// /// Bots can currently send animation files of up to 50 MB in size, this limit /// may be changed in the future. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendanimation). #[derive(Debug, Clone)] pub struct SendAnimation<'a> { bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format `@channelusername`) pub chat_id: ChatId, - /// Animation to send. pub animation: InputFile, - /// Duration of sent animation in seconds pub duration: Option, - /// Animation width pub width: Option, - /// Animation height pub height: Option, - /// Thumbnail of the file sent; can be ignored if thumbnail generation for - /// the file is supported server-side. The thumbnail should be in JPEG - /// format and less than 200 kB in size. A thumbnail‘s width and height - /// should not exceed 320. Ignored if the file is not uploaded using - /// [`InputFile::File`]. Thumbnails can’t be reused and can be only - /// uploaded as a new file, with [`InputFile::File`] - /// - /// [`InputFile::File`]: crate::types::InputFile::File pub thumb: Option, - /// Animation caption, `0`-`1024` characters pub caption: Option, - /// Send [Markdown] or [HTML], if you want Telegram apps to show - /// [bold, italic, fixed-width text or inline URLs] in the media caption. - /// - /// [Markdown]: crate::types::ParseMode::Markdown - /// [HTML]: crate::types::ParseMode::HTML - /// [bold, italic, fixed-width text or inline URLs]: - /// crate::types::ParseMode pub parse_mode: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. pub disable_notification: Option, - /// If the message is a reply, [id] of the original message - /// - /// [id]: crate::types::Message::id pub reply_to_message_id: Option, - /// Additional interface options pub reply_markup: Option, } @@ -116,6 +87,8 @@ impl<'a> SendAnimation<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, value: T) -> Self where T: Into, @@ -124,24 +97,46 @@ impl<'a> SendAnimation<'a> { self } + /// Animation to send. + pub fn animation(mut self, val: InputFile) -> Self { + self.animation = val; + self + } + + /// Duration of sent animation in seconds. pub fn duration(mut self, value: u32) -> Self { self.duration = Some(value); self } + /// Animation width. pub fn width(mut self, value: u32) -> Self { self.width = Some(value); self } + + /// Animation height. pub fn height(mut self, value: u32) -> Self { self.height = Some(value); self } + + /// Thumbnail of the file sent; can be ignored if thumbnail generation for + /// the file is supported server-side. + /// + /// The thumbnail should be in JPEG format and less than 200 kB in size. A + /// thumbnail‘s width and height should not exceed 320. Ignored if the + /// file is not uploaded using [`InputFile::File`]. Thumbnails can’t be + /// reused and can be only uploaded as a new file, with + /// [`InputFile::File`]. + /// + /// [`InputFile::File`]: crate::types::InputFile::File pub fn thumb(mut self, value: InputFile) -> Self { self.thumb = Some(value); self } + /// Animation caption, `0`-`1024` characters. pub fn caption(mut self, value: T) -> Self where T: Into, @@ -149,18 +144,35 @@ impl<'a> SendAnimation<'a> { self.caption = Some(value.into()); self } + + /// Send [Markdown] or [HTML], if you want Telegram apps to show + /// [bold, italic, fixed-width text or inline URLs] in the media caption. + /// + /// [Markdown]: crate::types::ParseMode::Markdown + /// [HTML]: crate::types::ParseMode::HTML + /// [bold, italic, fixed-width text or inline URLs]: + /// crate::types::ParseMode pub fn parse_mode(mut self, value: ParseMode) -> Self { self.parse_mode = Some(value); self } + + /// Sends the message silently. Users will receive a notification with no + /// sound. pub fn disable_notification(mut self, value: bool) -> Self { self.disable_notification = Some(value); self } + + /// If the message is a reply, [id] of the original message. + /// + /// [id]: crate::types::Message::id pub fn reply_to_message_id(mut self, value: i32) -> Self { self.reply_to_message_id = Some(value); self } + + /// Additional interface options. pub fn reply_markup(mut self, value: T) -> Self where T: Into, diff --git a/src/requests/all/send_audio.rs b/src/requests/all/send_audio.rs index 8ca739a2..cfa15597 100644 --- a/src/requests/all/send_audio.rs +++ b/src/requests/all/send_audio.rs @@ -6,50 +6,29 @@ use crate::{ }; /// Use this method to send audio files, if you want Telegram clients to display -/// them in the music player. Your audio must be in the .MP3 or .M4A format. On -/// success, the sent Message is returned. Bots can currently send audio files -/// of up to 50 MB in size, this limit may be changed in the future.For sending -/// voice messages, use the sendVoice method instead. +/// them in the music player. +/// +/// Your audio must be in the .MP3 or .M4A format. Bots can currently send audio +/// files of up to 50 MB in size, this limit may be changed in the future. +/// +/// For sending voice messages, use the [`Bot::send_voice`] method instead. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendaudio). +/// +/// [`Bot::send_voice`]: crate::Bot::send_voice #[derive(Debug, Clone)] pub struct SendAudio<'a> { bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Audio file to send. Pass a file_id as String to send an audio file that - /// exists on the Telegram servers (recommended), pass an HTTP URL as a - /// String for Telegram to get an audio file from the Internet, or upload a - /// new one using multipart/form-data. More info on Sending Files » audio: InputFile, - /// Audio caption, 0-1024 characters caption: Option, - /// Send Markdown or HTML, if you want Telegram apps to show bold, italic, - /// fixed-width text or inline URLs in the media caption. parse_mode: Option, - /// Duration of the audio in seconds duration: Option, - /// Performer performer: Option, - /// Track name title: Option, - /// Thumbnail of the file sent; can be ignored if thumbnail generation for - /// the file is supported server-side. The thumbnail should be in JPEG - /// format and less than 200 kB in size. A thumbnail‘s width and height - /// should not exceed 320. Ignored if the file is not uploaded using - /// multipart/form-data. Thumbnails can’t be reused and can be only - /// uploaded as a new file, so you can pass “attach://” - /// if the thumbnail was uploaded using multipart/form-data under - /// . More info on Sending Files » thumb: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -112,6 +91,8 @@ impl<'a> SendAudio<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -120,11 +101,24 @@ impl<'a> SendAudio<'a> { self } + /// Audio file to send. + /// + /// Pass [`InputFile::File`] to send a file that exists on + /// the Telegram servers (recommended), pass an [`InputFile::Url`] for + /// Telegram to get a .webp file from the Internet, or upload a new one + /// using [`InputFile::FileId`]. [More info on Sending Files »]. + /// + /// [`InputFile::File`]: crate::types::InputFile::File + /// [`InputFile::Url`]: crate::types::InputFile::Url + /// [`InputFile::FileId`]: crate::types::InputFile::FileId + /// + /// [More info on Sending Files »]: https://core.telegram.org/bots/api#sending-files pub fn audio(mut self, val: InputFile) -> Self { self.audio = val; self } + /// Audio caption, 0-1024 characters. pub fn caption(mut self, val: T) -> Self where T: Into, @@ -133,16 +127,25 @@ impl<'a> SendAudio<'a> { self } + /// Send [Markdown] or [HTML], if you want Telegram apps to show + /// [bold, italic, fixed-width text or inline URLs] in the media caption. + /// + /// [Markdown]: crate::types::ParseMode::Markdown + /// [HTML]: crate::types::ParseMode::HTML + /// [bold, italic, fixed-width text or inline URLs]: + /// crate::types::ParseMode pub fn parse_mode(mut self, val: ParseMode) -> Self { self.parse_mode = Some(val); self } + /// Duration of the audio in seconds. pub fn duration(mut self, val: i32) -> Self { self.duration = Some(val); self } + /// Performer. pub fn performer(mut self, val: T) -> Self where T: Into, @@ -151,6 +154,7 @@ impl<'a> SendAudio<'a> { self } + /// Track name. pub fn title(mut self, val: T) -> Self where T: Into, @@ -159,21 +163,44 @@ impl<'a> SendAudio<'a> { self } + /// Thumbnail of the file sent; can be ignored if thumbnail generation for + /// the file is supported server-side. + /// + /// The thumbnail should be in JPEG format and less than 200 kB in size. A + /// thumbnail‘s width and height should not exceed 320. Ignored if the + /// file is not uploaded using `multipart/form-data`. Thumbnails can’t + /// be reused and can be only uploaded as a new file, so you can pass + /// `attach://` if the thumbnail was uploaded using + /// `multipart/form-data` under ``. [More info on + /// Sending Files »]. + /// + /// [More info on Sending Files »]: https://core.telegram.org/bots/api#sending-files pub fn thumb(mut self, val: InputFile) -> Self { self.thumb = Some(val); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silantly]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. A JSON-serialized object for an [inline + /// keyboard], [custom reply keyboard], instructions to remove reply + /// keyboard or to force a reply from the user. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating + /// [custom reply keyboard]: https://core.telegram.org/bots#keyboards pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_chat_action.rs b/src/requests/all/send_chat_action.rs index 9efc04cb..db9ce64d 100644 --- a/src/requests/all/send_chat_action.rs +++ b/src/requests/all/send_chat_action.rs @@ -8,25 +8,28 @@ use crate::{ }; /// Use this method when you need to tell the user that something is happening -/// on the bot's side. The status is set for 5 seconds or less (when a message -/// arrives from your bot, Telegram clients clear its typing status). Returns -/// True on success.Example: The ImageBot needs some time to process a request -/// and upload the image. Instead of sending a text message along the lines of -/// “Retrieving image, please wait…”, the bot may use sendChatAction with action -/// = upload_photo. The user will see a “sending photo” status for the bot.We -/// only recommend using this method when a response from the bot will take a -/// noticeable amount of time to arrive. +/// on the bot's side. +/// +/// The status is set for 5 seconds or less (when a message arrives from your +/// bot, Telegram clients clear its typing status). +/// +/// ## Note +/// Example: The [ImageBot] needs some time to process a request and upload the +/// image. Instead of sending a text message along the lines of “Retrieving +/// image, please wait…”, the bot may use [`Bot::send_chat_action`] with `action +/// = upload_photo`. The user will see a `sending photo` status for the bot. +/// +/// We only recommend using this method when a response from the bot will take a +/// **noticeable** amount of time to arrive. +/// +/// [ImageBot]: https://t.me/imagebot +/// [`Bot::send_chat_action`]: crate::Bot::send_chat_action #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SendChatAction<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - - /// Type of action to broadcast. action: SendChatActionKind, } @@ -98,6 +101,8 @@ impl<'a> SendChatAction<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -106,6 +111,7 @@ impl<'a> SendChatAction<'a> { self } + /// Type of action to broadcast. pub fn action(mut self, val: SendChatActionKind) -> Self { self.action = val; self diff --git a/src/requests/all/send_contact.rs b/src/requests/all/send_contact.rs index 326c656b..6438420c 100644 --- a/src/requests/all/send_contact.rs +++ b/src/requests/all/send_contact.rs @@ -7,33 +7,21 @@ use crate::{ Bot, }; -/// Use this method to send phone contacts. On success, the sent Message is -/// returned. +/// Use this method to send phone contacts. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendcontact). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SendContact<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Contact's phone number phone_number: String, - /// Contact's first name first_name: String, - /// Contact's last name last_name: Option, - /// Additional data about the contact in the form of a vCard, 0-2048 bytes vcard: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove keyboard or to - /// force a reply from the user. reply_markup: Option, } @@ -80,6 +68,8 @@ impl<'a> SendContact<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -88,6 +78,7 @@ impl<'a> SendContact<'a> { self } + /// Contact's phone number. pub fn phone_number(mut self, val: T) -> Self where T: Into, @@ -96,6 +87,7 @@ impl<'a> SendContact<'a> { self } + /// Contact's first name. pub fn first_name(mut self, val: T) -> Self where T: Into, @@ -104,6 +96,7 @@ impl<'a> SendContact<'a> { self } + /// Contact's last name. pub fn last_name(mut self, val: T) -> Self where T: Into, @@ -112,6 +105,10 @@ impl<'a> SendContact<'a> { self } + /// Additional data about the contact in the form of a [vCard], 0-2048 + /// bytes. + /// + /// [vCard]: https://en.wikipedia.org/wiki/VCard pub fn vcard(mut self, val: T) -> Self where T: Into, @@ -120,16 +117,22 @@ impl<'a> SendContact<'a> { self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_document.rs b/src/requests/all/send_document.rs index d3e6cc36..c48aff2e 100644 --- a/src/requests/all/send_document.rs +++ b/src/requests/all/send_document.rs @@ -5,44 +5,22 @@ use crate::{ Bot, }; -/// Use this method to send general files. On success, the sent Message is -/// returned. Bots can currently send files of any type of up to 50 MB in size, -/// this limit may be changed in the future. +/// Use this method to send general files. +/// +/// Bots can currently send files of any type of up to 50 MB in size, this limit +/// may be changed in the future. +/// +/// [The official docs](https://core.telegram.org/bots/api#senddocument). #[derive(Debug, Clone)] pub struct SendDocument<'a> { bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// File to send. Pass a file_id as String to send a file that exists on - /// the Telegram servers (recommended), pass an HTTP URL as a String for - /// Telegram to get a file from the Internet, or upload a new one using - /// multipart/form-data. More info on Sending Files » document: InputFile, - /// Thumbnail of the file sent; can be ignored if thumbnail generation for - /// the file is supported server-side. The thumbnail should be in JPEG - /// format and less than 200 kB in size. A thumbnail‘s width and height - /// should not exceed 320. Ignored if the file is not uploaded using - /// multipart/form-data. Thumbnails can’t be reused and can be only - /// uploaded as a new file, so you can pass “attach://” - /// if the thumbnail was uploaded using multipart/form-data under - /// . More info on Sending Files » thumb: Option, - /// Document caption (may also be used when resending documents by - /// file_id), 0-1024 characters caption: Option, - /// Send Markdown or HTML, if you want Telegram apps to show bold, italic, - /// fixed-width text or inline URLs in the media caption. parse_mode: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -96,6 +74,8 @@ impl<'a> SendDocument<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -104,16 +84,36 @@ impl<'a> SendDocument<'a> { self } + /// File to send. Pass a file_id as String to send a file that exists on the + /// Telegram servers (recommended), pass an HTTP URL as a String for + /// Telegram to get a file from the Internet, or upload a new one using + /// `multipart/form-data`. [More info on Sending Files »]. + /// + /// [More info on Sending Files »]: https://core.telegram.org/bots/api#sending-files pub fn document(mut self, val: InputFile) -> Self { self.document = val; self } + /// Thumbnail of the file sent; can be ignored if thumbnail generation for + /// the file is supported server-side. + /// + /// The thumbnail should be in JPEG format and less than 200 kB in size. A + /// thumbnail‘s width and height should not exceed 320. Ignored if the + /// file is not uploaded using `multipart/form-data`. Thumbnails can’t + /// be reused and can be only uploaded as a new file, so you can pass + /// “attach://” if the thumbnail was uploaded using + /// `multipart/form-data` under ``. [More info on + /// Sending Files »]. + /// + /// [More info on Sending Files »]: https://core.telegram.org/bots/api#sending-files pub fn thumb(mut self, val: InputFile) -> Self { self.thumb = Some(val); self } + /// Document caption (may also be used when resending documents by + /// `file_id`), 0-1024 characters. pub fn caption(mut self, val: T) -> Self where T: Into, @@ -122,21 +122,34 @@ impl<'a> SendDocument<'a> { self } + /// Send [Markdown] or [HTML], if you want Telegram apps to show + /// [bold, italic, fixed-width text or inline URLs] in the media caption. + /// + /// [Markdown]: crate::types::ParseMode::Markdown + /// [HTML]: crate::types::ParseMode::HTML + /// [bold, italic, fixed-width text or inline URLs]: + /// crate::types::ParseMode pub fn parse_mode(mut self, val: ParseMode) -> Self { self.parse_mode = Some(val); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_game.rs b/src/requests/all/send_game.rs index 0480791f..bc1fe194 100644 --- a/src/requests/all/send_game.rs +++ b/src/requests/all/send_game.rs @@ -7,26 +7,18 @@ use crate::{ Bot, }; -/// Use this method to send a game. On success, the sent Message is returned. +/// Use this method to send a game. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendgame). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SendGame<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat chat_id: i32, - /// Short name of the game, serves as the unique identifier for the game. - /// Set up your games via Botfather. game_short_name: String, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// A JSON-serialized object for an inline keyboard. If empty, one ‘Play - /// game_title’ button will be shown. If not empty, the first button must - /// launch the game. reply_markup: Option, } @@ -61,11 +53,16 @@ impl<'a> SendGame<'a> { } } + /// Unique identifier for the target chat. pub fn chat_id(mut self, val: i32) -> Self { self.chat_id = val; self } + /// Short name of the game, serves as the unique identifier for the game. + /// Set up your games via [@Botfather]. + /// + /// [@Botfather]: https://t.me/botfather pub fn game_short_name(mut self, val: T) -> Self where T: Into, @@ -74,16 +71,26 @@ impl<'a> SendGame<'a> { self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// A JSON-serialized object for an [inline keyboard]. If empty, one `Play + /// game_title` button will be shown. If not empty, the first button must + /// launch the game. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating pub fn reply_markup(mut self, val: InlineKeyboardMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_invoice.rs b/src/requests/all/send_invoice.rs index 5d0bbcf4..85bf7115 100644 --- a/src/requests/all/send_invoice.rs +++ b/src/requests/all/send_invoice.rs @@ -7,70 +7,36 @@ use crate::{ Bot, }; -/// Use this method to send invoices. On success, the sent Message is returned. +/// Use this method to send invoices. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendinvoice). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SendInvoice<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target private chat chat_id: i32, - /// Product name, 1-32 characters title: String, - /// Product description, 1-255 characters description: String, - /// Bot-defined invoice payload, 1-128 bytes. This will not be displayed to - /// the user, use for your internal processes. payload: String, - /// Payments provider token, obtained via Botfather provider_token: String, - /// Unique deep-linking parameter that can be used to generate this invoice - /// when used as a start parameter start_parameter: String, - /// Three-letter ISO 4217 currency code, see more on currencies currency: String, - /// Price breakdown, a list of components (e.g. product price, tax, - /// discount, delivery cost, delivery tax, bonus, etc.) prices: Vec, - /// JSON-encoded data about the invoice, which will be shared with the - /// payment provider. A detailed description of required fields should be - /// provided by the payment provider. provider_data: Option, - /// URL of the product photo for the invoice. Can be a photo of the goods - /// or a marketing image for a service. People like it better when they see - /// what they are paying for. photo_url: Option, - /// Photo size photo_size: Option, - /// Photo width photo_width: Option, - /// Photo height photo_height: Option, - /// Pass True, if you require the user's full name to complete the order need_name: Option, - /// Pass True, if you require the user's phone number to complete the order need_phone_number: Option, - /// Pass True, if you require the user's email address to complete the - /// order need_email: Option, - /// Pass True, if you require the user's shipping address to complete the - /// order need_shipping_address: Option, - /// Pass True, if user's phone number should be sent to provider send_phone_number_to_provider: Option, - /// Pass True, if user's email address should be sent to provider send_email_to_provider: Option, - /// Pass True, if the final price depends on the shipping method is_flexible: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// A JSON-serialized object for an inline keyboard. If empty, one 'Pay - /// total price' button will be shown. If not empty, the first button must - /// be a Pay button. reply_markup: Option, } @@ -146,11 +112,13 @@ impl<'a> SendInvoice<'a> { } } + /// Unique identifier for the target private chat. pub fn chat_id(mut self, val: i32) -> Self { self.chat_id = val; self } + /// Product name, 1-32 characters. pub fn title(mut self, val: T) -> Self where T: Into, @@ -159,6 +127,7 @@ impl<'a> SendInvoice<'a> { self } + /// Product description, 1-255 characters. pub fn description(mut self, val: T) -> Self where T: Into, @@ -167,6 +136,8 @@ impl<'a> SendInvoice<'a> { self } + /// Bot-defined invoice payload, 1-128 bytes. This will not be displayed to + /// the user, use for your internal processes. pub fn payload(mut self, val: T) -> Self where T: Into, @@ -175,6 +146,9 @@ impl<'a> SendInvoice<'a> { self } + /// Payments provider token, obtained via [@Botfather]. + /// + /// [@Botfather]: https://t.me/botfather pub fn provider_token(mut self, val: T) -> Self where T: Into, @@ -183,6 +157,8 @@ impl<'a> SendInvoice<'a> { self } + /// Unique deep-linking parameter that can be used to generate this invoice + /// when used as a start parameter. pub fn start_parameter(mut self, val: T) -> Self where T: Into, @@ -191,6 +167,9 @@ impl<'a> SendInvoice<'a> { self } + /// Three-letter ISO 4217 currency code, see [more on currencies]. + /// + /// [more on currencies]: https://core.telegram.org/bots/payments#supported-currencies pub fn currency(mut self, val: T) -> Self where T: Into, @@ -199,6 +178,8 @@ impl<'a> SendInvoice<'a> { self } + /// Price breakdown, a list of components (e.g. product price, tax, + /// discount, delivery cost, delivery tax, bonus, etc.). pub fn prices(mut self, val: T) -> Self where T: Into>, @@ -207,6 +188,11 @@ impl<'a> SendInvoice<'a> { self } + /// JSON-encoded data about the invoice, which will be shared with the + /// payment provider. + /// + /// A detailed description of required fields should be provided by the + /// payment provider. pub fn provider_data(mut self, val: T) -> Self where T: Into, @@ -215,6 +201,10 @@ impl<'a> SendInvoice<'a> { self } + /// URL of the product photo for the invoice. + /// + /// Can be a photo of the goods or a marketing image for a service. People + /// like it better when they see what they are paying for. pub fn photo_url(mut self, val: T) -> Self where T: Into, @@ -223,67 +213,91 @@ impl<'a> SendInvoice<'a> { self } + /// Photo size. pub fn photo_size(mut self, val: i32) -> Self { self.photo_size = Some(val); self } + /// Photo width. pub fn photo_width(mut self, val: i32) -> Self { self.photo_width = Some(val); self } + /// Photo height. pub fn photo_height(mut self, val: i32) -> Self { self.photo_height = Some(val); self } + /// Pass `true`, if you require the user's full name to complete the order. pub fn need_name(mut self, val: bool) -> Self { self.need_name = Some(val); self } + /// Pass `true`, if you require the user's phone number to complete the + /// order. pub fn need_phone_number(mut self, val: bool) -> Self { self.need_phone_number = Some(val); self } + /// Pass `true`, if you require the user's email address to complete the + /// order. pub fn need_email(mut self, val: bool) -> Self { self.need_email = Some(val); self } + /// Pass `true`, if you require the user's shipping address to complete the + /// order. pub fn need_shipping_address(mut self, val: bool) -> Self { self.need_shipping_address = Some(val); self } + /// Pass `true`, if user's phone number should be sent to provider. pub fn send_phone_number_to_provider(mut self, val: bool) -> Self { self.send_phone_number_to_provider = Some(val); self } + /// Pass `true`, if user's email address should be sent to provider. pub fn send_email_to_provider(mut self, val: bool) -> Self { self.send_email_to_provider = Some(val); self } + /// Pass `true`, if the final price depends on the shipping method. #[allow(clippy::wrong_self_convention)] pub fn is_flexible(mut self, val: bool) -> Self { self.is_flexible = Some(val); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// A JSON-serialized object for an [inline keyboard]. + /// + /// If empty, one 'Pay `total price`' button will be shown. If not empty, + /// the first button must be a Pay button. + /// + /// [inlint keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating pub fn reply_markup(mut self, val: InlineKeyboardMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_location.rs b/src/requests/all/send_location.rs index e29582db..d2b61ad4 100644 --- a/src/requests/all/send_location.rs +++ b/src/requests/all/send_location.rs @@ -7,32 +7,20 @@ use crate::{ Bot, }; -/// Use this method to send point on the map. On success, the sent Message is -/// returned. +/// Use this method to send point on the map. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendlocation). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SendLocation<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Latitude of the location latitude: f32, - /// Longitude of the location longitude: f32, - /// Period in seconds for which the location will be updated (see Live - /// Locations, should be between 60 and 86400. live_period: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -74,6 +62,8 @@ impl<'a> SendLocation<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -82,31 +72,48 @@ impl<'a> SendLocation<'a> { self } + /// Latitude of the location. pub fn latitude(mut self, val: f32) -> Self { self.latitude = val; self } + /// Longitude of the location. pub fn longitude(mut self, val: f32) -> Self { self.longitude = val; self } + /// Period in seconds for which the location will be updated (see [Live + /// Locations], should be between 60 and 86400). + /// + /// [Live Locations]: https://telegram.org/blog/live-locations pub fn live_period(mut self, val: i64) -> Self { self.live_period = Some(val); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// A JSON-serialized object for an [inline keyboard]. + /// + /// If empty, one 'Pay `total price`' button will be shown. If not empty, + /// the first button must be a Pay button. + /// + /// [inlint keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_media_group.rs b/src/requests/all/send_media_group.rs index e7bd331d..2a8e3268 100644 --- a/src/requests/all/send_media_group.rs +++ b/src/requests/all/send_media_group.rs @@ -5,22 +5,15 @@ use crate::{ Bot, }; -/// Use this method to send a group of photos or videos as an album. On success, -/// an array of the sent Messages is returned. +/// Use this method to send a group of photos or videos as an album. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendmediagroup). #[derive(Debug, Clone)] pub struct SendMediaGroup<'a> { bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// A JSON-serialized array describing photos and videos to be sent, must - /// include 2–10 items media: Vec, // TODO: InputMediaPhoto and InputMediaVideo - /// Sends the messages silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the messages are a reply, ID of the original message reply_to_message_id: Option, } @@ -65,6 +58,8 @@ impl<'a> SendMediaGroup<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -73,6 +68,8 @@ impl<'a> SendMediaGroup<'a> { self } + /// A JSON-serialized array describing photos and videos to be sent, must + /// include 2–10 items. pub fn media(mut self, val: T) -> Self where T: Into>, @@ -81,11 +78,16 @@ impl<'a> SendMediaGroup<'a> { self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the messages are a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self diff --git a/src/requests/all/send_message.rs b/src/requests/all/send_message.rs index 3b4ff715..d47eaab1 100644 --- a/src/requests/all/send_message.rs +++ b/src/requests/all/send_message.rs @@ -9,38 +9,18 @@ use crate::{ /// Use this method to send text messages. /// -/// On success, the sent [`Message`] is returned. -/// -/// [`Message`]: crate::types::Message +/// [The official docs](https://core.telegram.org/bots/api#sendmessage). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SendMessage<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format `@channelusername`) pub chat_id: ChatId, - /// Text of the message to be sent pub text: String, - /// Send [Markdown] or [HTML], if you want Telegram apps to show - /// [bold, italic, fixed-width text or inline URLs] in your bot's message. - /// - /// [Markdown]: crate::types::ParseMode::Markdown - /// [HTML]: crate::types::ParseMode::HTML - /// [bold, italic, fixed-width text or inline URLs]: - /// crate::types::ParseMode pub parse_mode: Option, - /// Disables link previews for links in this message pub disable_web_page_preview: Option, - /// Sends the message silently. - /// Users will receive a notification with no sound. pub disable_notification: Option, - /// If the message is a reply, [id] of the original message - /// - /// [id]: crate::types::Message::id pub reply_to_message_id: Option, - /// Additional interface options. pub reply_markup: Option, } @@ -77,6 +57,8 @@ impl<'a> SendMessage<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, value: T) -> Self where T: Into, @@ -85,6 +67,7 @@ impl<'a> SendMessage<'a> { self } + /// Text of the message to be sent. pub fn text(mut self, value: T) -> Self where T: Into, @@ -93,26 +76,47 @@ impl<'a> SendMessage<'a> { self } + /// Send [Markdown] or [HTML], if you want Telegram apps to show + /// [bold, italic, fixed-width text or inline URLs] in the media caption. + /// + /// [Markdown]: crate::types::ParseMode::Markdown + /// [HTML]: crate::types::ParseMode::HTML + /// [bold, italic, fixed-width text or inline URLs]: + /// crate::types::ParseMode pub fn parse_mode(mut self, value: ParseMode) -> Self { self.parse_mode = Some(value); self } + /// Disables link previews for links in this message. pub fn disable_web_page_preview(mut self, value: bool) -> Self { self.disable_web_page_preview = Some(value); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, value: bool) -> Self { self.disable_notification = Some(value); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, value: i32) -> Self { self.reply_to_message_id = Some(value); self } + /// Additional interface options. + /// + /// A JSON-serialized object for an [inline keyboard], [custom reply + /// keyboard], instructions to remove reply keyboard or to force a reply + /// from the user. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating + /// [custom reply keyboard]: https://core.telegram.org/bots#keyboards pub fn reply_markup(mut self, value: T) -> Self where T: Into, diff --git a/src/requests/all/send_photo.rs b/src/requests/all/send_photo.rs index 92524d65..7a65f97e 100644 --- a/src/requests/all/send_photo.rs +++ b/src/requests/all/send_photo.rs @@ -5,33 +5,18 @@ use crate::{ Bot, }; -/// Use this method to send photos. On success, the sent Message is returned. +/// Use this method to send photos. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendphoto). #[derive(Debug, Clone)] pub struct SendPhoto<'a> { bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Photo to send. Pass a file_id as String to send a photo that exists on - /// the Telegram servers (recommended), pass an HTTP URL as a String for - /// Telegram to get a photo from the Internet, or upload a new photo using - /// multipart/form-data. More info on Sending Files » photo: InputFile, - /// Photo caption (may also be used when resending photos by file_id), - /// 0-1024 characters caption: Option, - /// Send Markdown or HTML, if you want Telegram apps to show bold, italic, - /// fixed-width text or inline URLs in the media caption. parse_mode: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -82,6 +67,8 @@ impl<'a> SendPhoto<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -90,11 +77,25 @@ impl<'a> SendPhoto<'a> { self } + /// Photo to send. + /// + /// Pass [`InputFile::File`] to send a photo that exists on + /// the Telegram servers (recommended), pass an [`InputFile::Url`] for + /// Telegram to get a .webp file from the Internet, or upload a new one + /// using [`InputFile::FileId`]. [More info on Sending Files »]. + /// + /// [`InputFile::File`]: crate::types::InputFile::File + /// [`InputFile::Url`]: crate::types::InputFile::Url + /// [`InputFile::FileId`]: crate::types::InputFile::FileId + /// + /// [More info on Sending Files »]: https://core.telegram.org/bots/api#sending-files pub fn photo(mut self, val: InputFile) -> Self { self.photo = val; self } + ///Photo caption (may also be used when resending photos by file_id), + /// 0-1024 characters. pub fn caption(mut self, val: T) -> Self where T: Into, @@ -103,21 +104,39 @@ impl<'a> SendPhoto<'a> { self } + /// Send [Markdown] or [HTML], if you want Telegram apps to show + /// [bold, italic, fixed-width text or inline URLs] in the media caption. + /// + /// [Markdown]: crate::types::ParseMode::Markdown + /// [HTML]: crate::types::ParseMode::HTML + /// [bold, italic, fixed-width text or inline URLs]: + /// crate::types::ParseMode pub fn parse_mode(mut self, val: ParseMode) -> Self { self.parse_mode = Some(val); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. A JSON-serialized object for an [inline + /// keyboard], [custom reply keyboard], instructions to remove reply + /// keyboard or to force a reply from the user. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating + /// [custom reply keyboard]: https://core.telegram.org/bots#keyboards pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_poll.rs b/src/requests/all/send_poll.rs index 0bd8e6ba..e6fdeb74 100644 --- a/src/requests/all/send_poll.rs +++ b/src/requests/all/send_poll.rs @@ -8,29 +8,19 @@ use crate::{ }; /// Use this method to send a native poll. A native poll can't be sent to a -/// private chat. On success, the sent Message is returned. +/// private chat. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendpoll). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SendPoll<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername). A native poll can't be sent to a - /// private chat. chat_id: ChatId, - /// Poll question, 1-255 characters question: String, - /// List of answer options, 2-10 strings 1-100 characters each options: Vec, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -75,6 +65,10 @@ impl<'a> SendPoll<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). + /// + /// A native poll can't be sent to a private chat. pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -83,6 +77,7 @@ impl<'a> SendPoll<'a> { self } + /// Poll question, 1-255 characters. pub fn question(mut self, val: T) -> Self where T: Into, @@ -91,6 +86,7 @@ impl<'a> SendPoll<'a> { self } + /// List of answer options, 2-10 strings 1-100 characters each. pub fn options(mut self, val: T) -> Self where T: Into>, @@ -99,16 +95,29 @@ impl<'a> SendPoll<'a> { self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. + /// + /// A JSON-serialized object for an [inline keyboard], [custom reply + /// keyboard], instructions to remove reply keyboard or to force a reply + /// from the user. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating + /// [custom reply keyboard]: https://core.telegram.org/bots#keyboards pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_sticker.rs b/src/requests/all/send_sticker.rs index 865fe744..300a2cc2 100644 --- a/src/requests/all/send_sticker.rs +++ b/src/requests/all/send_sticker.rs @@ -5,28 +5,18 @@ use crate::{ Bot, }; -/// Use this method to send static .WEBP or animated .TGS stickers. On success, -/// the sent Message is returned. +/// Use this method to send static .WEBP or [animated] .TGS stickers. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendsticker). +/// +/// [animated]: https://telegram.org/blog/animated-stickers #[derive(Debug, Clone)] pub struct SendSticker<'a> { bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Sticker to send. Pass a file_id as String to send a file that exists on - /// the Telegram servers (recommended), pass an HTTP URL as a String for - /// Telegram to get a .webp file from the Internet, or upload a new one - /// using multipart/form-data. More info on Sending Files » sticker: InputFile, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -71,6 +61,8 @@ impl<'a> SendSticker<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -79,21 +71,44 @@ impl<'a> SendSticker<'a> { self } + /// Sticker to send. + /// + /// Pass [`InputFile::File`] to send a file that exists on + /// the Telegram servers (recommended), pass an [`InputFile::Url`] for + /// Telegram to get a .webp file from the Internet, or upload a new one + /// using [`InputFile::FileId`]. [More info on Sending Files »]. + /// + /// [`InputFile::File`]: crate::types::InputFile::File + /// [`InputFile::Url`]: crate::types::InputFile::Url + /// [`InputFile::FileId`]: crate::types::InputFile::FileId pub fn sticker(mut self, val: InputFile) -> Self { self.sticker = val; self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. + /// + /// A JSON-serialized object for an [inline keyboard], [custom reply + /// keyboard], instructions to remove reply keyboard or to force a reply + /// from the user. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating + /// [custom reply keyboard]: https://core.telegram.org/bots#keyboards pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_venue.rs b/src/requests/all/send_venue.rs index e6ac22a7..f0f28ae6 100644 --- a/src/requests/all/send_venue.rs +++ b/src/requests/all/send_venue.rs @@ -7,39 +7,23 @@ use crate::{ Bot, }; -/// Use this method to send information about a venue. On success, the sent -/// Message is returned. +/// Use this method to send information about a venue. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendvenue). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SendVenue<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Latitude of the venue latitude: f32, - /// Longitude of the venue longitude: f32, - /// Name of the venue title: String, - /// Address of the venue address: String, - /// Foursquare identifier of the venue foursquare_id: Option, - /// Foursquare type of the venue, if known. (For example, - /// “arts_entertainment/default”, “arts_entertainment/aquarium” or - /// “food/icecream”.) foursquare_type: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -90,6 +74,8 @@ impl<'a> SendVenue<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -98,16 +84,19 @@ impl<'a> SendVenue<'a> { self } + /// Latitude of the venue. pub fn latitude(mut self, val: f32) -> Self { self.latitude = val; self } + /// Longitude of the venue. pub fn longitude(mut self, val: f32) -> Self { self.longitude = val; self } + /// Name of the venue. pub fn title(mut self, val: T) -> Self where T: Into, @@ -116,6 +105,7 @@ impl<'a> SendVenue<'a> { self } + /// Address of the venue. pub fn address(mut self, val: T) -> Self where T: Into, @@ -124,6 +114,7 @@ impl<'a> SendVenue<'a> { self } + /// Foursquare identifier of the venue. pub fn foursquare_id(mut self, val: T) -> Self where T: Into, @@ -132,6 +123,10 @@ impl<'a> SendVenue<'a> { self } + /// Foursquare type of the venue, if known. + /// + /// For example, `arts_entertainment/default`, `arts_entertainment/aquarium` + /// or `food/icecream`. pub fn foursquare_type(mut self, val: T) -> Self where T: Into, @@ -140,16 +135,29 @@ impl<'a> SendVenue<'a> { self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. + /// + /// A JSON-serialized object for an [inline keyboard], [custom reply + /// keyboard], instructions to remove reply keyboard or to force a reply + /// from the user. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating + /// [custom reply keyboard]: https://core.telegram.org/bots#keyboards pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_video.rs b/src/requests/all/send_video.rs index ac5d44ba..ed493291 100644 --- a/src/requests/all/send_video.rs +++ b/src/requests/all/send_video.rs @@ -6,52 +6,26 @@ use crate::{ }; /// Use this method to send video files, Telegram clients support mp4 videos -/// (other formats may be sent as Document). On success, the sent Message is -/// returned. Bots can currently send video files of up to 50 MB in size, this +/// (other formats may be sent as Document). +/// +/// Bots can currently send video files of up to 50 MB in size, this /// limit may be changed in the future. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendvideo). #[derive(Debug, Clone)] pub struct SendVideo<'a> { bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Video to send. Pass a file_id as String to send a video that exists on - /// the Telegram servers (recommended), pass an HTTP URL as a String for - /// Telegram to get a video from the Internet, or upload a new video using - /// multipart/form-data. More info on Sending Files » video: InputFile, - /// Duration of sent video in seconds duration: Option, - /// Video width width: Option, - /// Video height height: Option, - /// Thumbnail of the file sent; can be ignored if thumbnail generation for - /// the file is supported server-side. The thumbnail should be in JPEG - /// format and less than 200 kB in size. A thumbnail‘s width and height - /// should not exceed 320. Ignored if the file is not uploaded using - /// multipart/form-data. Thumbnails can’t be reused and can be only - /// uploaded as a new file, so you can pass “attach://” - /// if the thumbnail was uploaded using multipart/form-data under - /// . More info on Sending Files » thumb: Option, - /// Video caption (may also be used when resending videos by file_id), - /// 0-1024 characters caption: Option, - /// Send Markdown or HTML, if you want Telegram apps to show bold, italic, - /// fixed-width text or inline URLs in the media caption. parse_mode: Option, - /// Pass True, if the uploaded video is suitable for streaming supports_streaming: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -117,6 +91,8 @@ impl<'a> SendVideo<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -125,31 +101,58 @@ impl<'a> SendVideo<'a> { self } + /// Video to sent. + /// + /// Pass [`InputFile::File`] to send a file that exists on + /// the Telegram servers (recommended), pass an [`InputFile::Url`] for + /// Telegram to get a .webp file from the Internet, or upload a new one + /// using [`InputFile::FileId`]. [More info on Sending Files »]. + /// + /// [`InputFile::File`]: crate::types::InputFile::File + /// [`InputFile::Url`]: crate::types::InputFile::Url + /// [`InputFile::FileId`]: crate::types::InputFile::FileId pub fn video(mut self, val: InputFile) -> Self { self.video = val; self } + /// Duration of sent video in seconds. pub fn duration(mut self, val: i32) -> Self { self.duration = Some(val); self } + /// Video width. pub fn width(mut self, val: i32) -> Self { self.width = Some(val); self } + /// Video height. pub fn height(mut self, val: i32) -> Self { self.height = Some(val); self } + /// Thumbnail of the file sent; can be ignored if thumbnail generation for + /// the file is supported server-side. + /// + /// The thumbnail should be in JPEG format and less than 200 kB in size. A + /// thumbnail‘s width and height should not exceed 320. Ignored if the + /// file is not uploaded using `multipart/form-data`. Thumbnails can’t be + /// reused and can be only uploaded as a new file, so you can pass + /// `attach://` if the thumbnail was uploaded using + /// `multipart/form-data` under ``. [More info on Sending + /// Files »]. + /// + /// [More info on Sending Files »]: https://core.telegram.org/bots/api#sending-files pub fn thumb(mut self, val: InputFile) -> Self { self.thumb = Some(val); self } + /// Video caption (may also be used when resending videos by file_id), + /// 0-1024 characters. pub fn caption(mut self, val: T) -> Self where T: Into, @@ -158,26 +161,47 @@ impl<'a> SendVideo<'a> { self } + /// Send [Markdown] or [HTML], if you want Telegram apps to show + /// [bold, italic, fixed-width text or inline URLs] in the media caption. + /// + /// [Markdown]: crate::types::ParseMode::Markdown + /// [HTML]: crate::types::ParseMode::HTML + /// [bold, italic, fixed-width text or inline URLs]: + /// crate::types::ParseMode pub fn parse_mode(mut self, val: ParseMode) -> Self { self.parse_mode = Some(val); self } + /// Pass `true`, if the uploaded video is suitable for streaming. pub fn supports_streaming(mut self, val: bool) -> Self { self.supports_streaming = Some(val); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. + /// + /// A JSON-serialized object for an [inline keyboard], [custom reply + /// keyboard], instructions to remove reply keyboard or to force a reply + /// from the user. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating + /// [custom reply keyboard]: https://core.telegram.org/bots#keyboards pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_video_note.rs b/src/requests/all/send_video_note.rs index cb4229a5..2b260f4c 100644 --- a/src/requests/all/send_video_note.rs +++ b/src/requests/all/send_video_note.rs @@ -5,42 +5,22 @@ use crate::{ Bot, }; -/// As of v.4.0, Telegram clients support rounded square mp4 videos of up to 1 -/// minute long. Use this method to send video messages. On success, the sent -/// Message is returned. +/// As of [v.4.0], Telegram clients support rounded square mp4 videos of up to 1 +/// minute long. Use this method to send video messages. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendvideonote). +/// +/// [v.4.0]: https://telegram.org/blog/video-messages-and-telescope #[derive(Debug, Clone)] pub struct SendVideoNote<'a> { bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Video note to send. Pass a file_id as String to send a video note that - /// exists on the Telegram servers (recommended) or upload a new video - /// using multipart/form-data. More info on Sending Files ». Sending video - /// notes by a URL is currently unsupported video_note: InputFile, - /// Duration of sent video in seconds duration: Option, - /// Video width and height, i.e. diameter of the video message length: Option, - /// Thumbnail of the file sent; can be ignored if thumbnail generation for - /// the file is supported server-side. The thumbnail should be in JPEG - /// format and less than 200 kB in size. A thumbnail‘s width and height - /// should not exceed 320. Ignored if the file is not uploaded using - /// multipart/form-data. Thumbnails can’t be reused and can be only - /// uploaded as a new file, so you can pass “attach://” - /// if the thumbnail was uploaded using multipart/form-data under - /// . More info on Sending Files » thumb: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -98,6 +78,8 @@ impl<'a> SendVideoNote<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -106,36 +88,71 @@ impl<'a> SendVideoNote<'a> { self } + /// Video note to send. + /// + /// Pass [`InputFile::File`] to send a file that exists on + /// the Telegram servers (recommended), pass an [`InputFile::Url`] for + /// Telegram to get a .webp file from the Internet, or upload a new one + /// using [`InputFile::FileId`]. [More info on Sending Files »]. + /// + /// [`InputFile::File`]: crate::types::InputFile::File + /// [`InputFile::Url`]: crate::types::InputFile::Url + /// [`InputFile::FileId`]: crate::types::InputFile::FileId pub fn video_note(mut self, val: InputFile) -> Self { self.video_note = val; self } + /// Duration of sent video in seconds. pub fn duration(mut self, val: i32) -> Self { self.duration = Some(val); self } + /// Video width and height, i.e. diameter of the video message. pub fn length(mut self, val: i32) -> Self { self.length = Some(val); self } + /// Thumbnail of the file sent; can be ignored if thumbnail generation for + /// the file is supported server-side. + /// + /// The thumbnail should be in JPEG format and less than 200 kB in size. A + /// thumbnail‘s width and height should not exceed 320. Ignored if the + /// file is not uploaded using `multipart/form-data`. Thumbnails can’t + /// be reused and can be only uploaded as a new file, so you can pass + /// `attach://` if the thumbnail was uploaded using + /// `multipart/form-data` under ``. [More info on + /// Sending Files »]. pub fn thumb(mut self, val: InputFile) -> Self { self.thumb = Some(val); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. + /// + /// A JSON-serialized object for an [inline keyboard], [custom reply + /// keyboard], instructions to remove reply keyboard or to force a reply + /// from the user. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating + /// [custom reply keyboard]: https://core.telegram.org/bots#keyboards pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/send_voice.rs b/src/requests/all/send_voice.rs index 49bc29bc..5e514f6d 100644 --- a/src/requests/all/send_voice.rs +++ b/src/requests/all/send_voice.rs @@ -6,38 +6,27 @@ use crate::{ }; /// Use this method to send audio files, if you want Telegram clients to display -/// the file as a playable voice message. For this to work, your audio must be -/// in an .ogg file encoded with OPUS (other formats may be sent as Audio or -/// Document). On success, the sent Message is returned. Bots can currently send -/// voice messages of up to 50 MB in size, this limit may be changed in the +/// the file as a playable voice message. +/// +/// For this to work, your audio must be in an .ogg file encoded with OPUS +/// (other formats may be sent as [`Audio`] or [`Document`]). Bots can currently +/// send voice messages of up to 50 MB in size, this limit may be changed in the /// future. +/// +/// [The official docs](https://core.telegram.org/bots/api#sendvoice). +/// +/// [`Audio`]: crate::types::Audio +/// [`Document`]: crate::types::Document #[derive(Debug, Clone)] pub struct SendVoice<'a> { bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Audio file to send. Pass a file_id as String to send a file that exists - /// on the Telegram servers (recommended), pass an HTTP URL as a String for - /// Telegram to get a file from the Internet, or upload a new one using - /// multipart/form-data. More info on Sending Files » voice: InputFile, - /// Voice message caption, 0-1024 characters caption: Option, - /// Send Markdown or HTML, if you want Telegram apps to show bold, italic, - /// fixed-width text or inline URLs in the media caption. parse_mode: Option, - /// Duration of the voice message in seconds duration: Option, - /// Sends the message silently. Users will receive a notification with no - /// sound. disable_notification: Option, - /// If the message is a reply, ID of the original message reply_to_message_id: Option, - /// Additional interface options. A JSON-serialized object for an inline - /// keyboard, custom reply keyboard, instructions to remove reply keyboard - /// or to force a reply from the user. reply_markup: Option, } @@ -91,6 +80,8 @@ impl<'a> SendVoice<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -99,11 +90,22 @@ impl<'a> SendVoice<'a> { self } + /// Audio file to send. + /// + /// Pass [`InputFile::File`] to send a file that exists on + /// the Telegram servers (recommended), pass an [`InputFile::Url`] for + /// Telegram to get a .webp file from the Internet, or upload a new one + /// using [`InputFile::FileId`]. [More info on Sending Files »]. + /// + /// [`InputFile::File`]: crate::types::InputFile::File + /// [`InputFile::Url`]: crate::types::InputFile::Url + /// [`InputFile::FileId`]: crate::types::InputFile::FileId pub fn voice(mut self, val: InputFile) -> Self { self.voice = val; self } + /// Voice message caption, 0-1024 characters. pub fn caption(mut self, val: T) -> Self where T: Into, @@ -112,26 +114,47 @@ impl<'a> SendVoice<'a> { self } + /// Send [Markdown] or [HTML], if you want Telegram apps to show + /// [bold, italic, fixed-width text or inline URLs] in the media caption. + /// + /// [Markdown]: crate::types::ParseMode::Markdown + /// [HTML]: crate::types::ParseMode::HTML + /// [bold, italic, fixed-width text or inline URLs]: + /// crate::types::ParseMode pub fn parse_mode(mut self, val: ParseMode) -> Self { self.parse_mode = Some(val); self } + /// Duration of the voice message in seconds. pub fn duration(mut self, val: i32) -> Self { self.duration = Some(val); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_notification(mut self, val: bool) -> Self { self.disable_notification = Some(val); self } + /// If the message is a reply, ID of the original message. pub fn reply_to_message_id(mut self, val: i32) -> Self { self.reply_to_message_id = Some(val); self } + /// Additional interface options. + /// + /// A JSON-serialized object for an [inline keyboard], [custom reply + /// keyboard], instructions to remove reply keyboard or to force a reply + /// from the user. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating + /// [custom reply keyboard]: https://core.telegram.org/bots#keyboards pub fn reply_markup(mut self, val: ReplyMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/set_chat_administrator_custom_title.rs b/src/requests/all/set_chat_administrator_custom_title.rs index 4f90f266..e0e91b6d 100644 --- a/src/requests/all/set_chat_administrator_custom_title.rs +++ b/src/requests/all/set_chat_administrator_custom_title.rs @@ -9,22 +9,16 @@ use crate::{ /// Use this method to set a custom title for an administrator in a supergroup /// promoted by the bot. +/// +/// [The official docs](https://core.telegram.org/bots/api#setchatadministratorcustomtitle). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SetChatAdministratorCustomTitle<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target - /// supergroup (in the format `@supergroupusername`) - pub chat_id: ChatId, - - /// Unique identifier of the target user - pub user_id: i32, - - /// New custom title for the administrator; 0-16 characters, emoji are not - /// allowed - pub custom_title: String, + chat_id: ChatId, + user_id: i32, + custom_title: String, } #[async_trait::async_trait] @@ -63,6 +57,8 @@ impl<'a> SetChatAdministratorCustomTitle<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -71,11 +67,14 @@ impl<'a> SetChatAdministratorCustomTitle<'a> { self } + /// Unique identifier of the target user. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self } + /// New custom title for the administrator; 0-16 characters, emoji are not + /// allowed. pub fn custom_title(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/set_chat_description.rs b/src/requests/all/set_chat_description.rs index a3acb225..1b5ca9c7 100644 --- a/src/requests/all/set_chat_description.rs +++ b/src/requests/all/set_chat_description.rs @@ -8,18 +8,18 @@ use crate::{ }; /// Use this method to change the description of a group, a supergroup or a -/// channel. The bot must be an administrator in the chat for this to work and -/// must have the appropriate admin rights. Returns True on success. +/// channel. +/// +/// The bot must be an administrator in the chat for this to work and must have +/// the appropriate admin rights. +/// +/// [The official docs](https://core.telegram.org/bots/api#setchatdescription). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SetChatDescription<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// New chat description, 0-255 characters description: Option, } @@ -51,6 +51,8 @@ impl<'a> SetChatDescription<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -59,6 +61,7 @@ impl<'a> SetChatDescription<'a> { self } + /// New chat description, 0-255 characters. pub fn description(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/set_chat_permissions.rs b/src/requests/all/set_chat_permissions.rs index 2ea69ed3..854d4e7a 100644 --- a/src/requests/all/set_chat_permissions.rs +++ b/src/requests/all/set_chat_permissions.rs @@ -7,19 +7,18 @@ use crate::{ Bot, }; -/// Use this method to set default chat permissions for all members. The bot -/// must be an administrator in the group or a supergroup for this to work and -/// must have the can_restrict_members admin rights. Returns True on success. +/// Use this method to set default chat permissions for all members. +/// +/// The bot must be an administrator in the group or a supergroup for this to +/// work and must have the can_restrict_members admin rights. +/// +/// [The official docs](https://core.telegram.org/bots/api#setchatpermissions). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SetChatPermissions<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target - /// supergroup (in the format @supergroupusername) chat_id: ChatId, - /// New default chat permissions permissions: ChatPermissions, } @@ -55,6 +54,8 @@ impl<'a> SetChatPermissions<'a> { } } + /// Unique identifier for the target chat or username of the target + /// supergroup (in the format `@supergroupusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -63,6 +64,7 @@ impl<'a> SetChatPermissions<'a> { self } + /// New default chat permissions. pub fn permissions(mut self, val: ChatPermissions) -> Self { self.permissions = val; self diff --git a/src/requests/all/set_chat_photo.rs b/src/requests/all/set_chat_photo.rs index 991b52cc..da28bd84 100644 --- a/src/requests/all/set_chat_photo.rs +++ b/src/requests/all/set_chat_photo.rs @@ -7,20 +7,18 @@ use crate::{ Bot, }; -/// Use this method to set a new profile photo for the chat. Photos can't be -/// changed for private chats. The bot must be an administrator in the chat for -/// this to work and must have the appropriate admin rights. Returns True on -/// success. +/// Use this method to set a new profile photo for the chat. +/// +/// Photos can't be changed for private chats. The bot must be an administrator +/// in the chat for this to work and must have the appropriate admin rights. +/// +/// [The official docs](https://core.telegram.org/bots/api#setchatphoto). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SetChatPhoto<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// New chat photo, uploaded using multipart/form-data photo: InputFile, } @@ -52,6 +50,8 @@ impl<'a> SetChatPhoto<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -60,6 +60,7 @@ impl<'a> SetChatPhoto<'a> { self } + /// New chat photo, uploaded using multipart/form-data. pub fn photo(mut self, val: InputFile) -> Self { self.photo = val; self diff --git a/src/requests/all/set_chat_sticker_set.rs b/src/requests/all/set_chat_sticker_set.rs index 5f83dc2a..e679f8b8 100644 --- a/src/requests/all/set_chat_sticker_set.rs +++ b/src/requests/all/set_chat_sticker_set.rs @@ -7,21 +7,19 @@ use crate::{ Bot, }; -/// Use this method to set a new group sticker set for a supergroup. The bot -/// must be an administrator in the chat for this to work and must have the -/// appropriate admin rights. Use the field can_set_sticker_set optionally +/// Use this method to set a new group sticker set for a supergroup. +/// +/// The bot must be an administrator in the chat for this to work and must have +/// the appropriate admin rights. Use the field can_set_sticker_set optionally /// returned in getChat requests to check if the bot can use this method. -/// Returns True on success. +/// +/// [The official docs](https://core.telegram.org/bots/api#setchatstickerset). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SetChatStickerSet<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target - /// supergroup (in the format @supergroupusername) chat_id: ChatId, - /// Name of the sticker set to be set as the group sticker set sticker_set_name: String, } @@ -59,6 +57,8 @@ impl<'a> SetChatStickerSet<'a> { } } + /// Unique identifier for the target chat or username of the target + /// supergroup (in the format `@supergroupusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -67,6 +67,7 @@ impl<'a> SetChatStickerSet<'a> { self } + /// Name of the sticker set to be set as the group sticker set. pub fn sticker_set_name(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/set_chat_title.rs b/src/requests/all/set_chat_title.rs index ee50d428..2f199d10 100644 --- a/src/requests/all/set_chat_title.rs +++ b/src/requests/all/set_chat_title.rs @@ -7,19 +7,18 @@ use crate::{ Bot, }; -/// Use this method to change the title of a chat. Titles can't be changed for -/// private chats. The bot must be an administrator in the chat for this to work -/// and must have the appropriate admin rights. Returns True on success. +/// Use this method to change the title of a chat. +/// +/// Titles can't be changed for private chats. The bot must be an administrator +/// in the chat for this to work and must have the appropriate admin rights. +/// +/// [The official docs](https://core.telegram.org/bots/api#setchattitle). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SetChatTitle<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// New chat title, 1-255 characters title: String, } @@ -53,6 +52,8 @@ impl<'a> SetChatTitle<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -61,6 +62,7 @@ impl<'a> SetChatTitle<'a> { self } + /// New chat title, 1-255 characters. pub fn title(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/set_game_score.rs b/src/requests/all/set_game_score.rs index 08eba77a..146bf7a6 100644 --- a/src/requests/all/set_game_score.rs +++ b/src/requests/all/set_game_score.rs @@ -7,28 +7,27 @@ use crate::{ Bot, }; -/// Use this method to set the score of the specified user in a game. On -/// success, if the message was sent by the bot, returns the edited Message, -/// otherwise returns True. Returns an error, if the new score is not greater -/// than the user's current score in the chat and force is False. +/// Use this method to set the score of the specified user in a game. +/// +/// On success, if the message was sent by the bot, returns the edited +/// [`Message`], otherwise returns [`True`]. Returns an error, if the new score +/// is not greater than the user's current score in the chat and force is +/// `false`. +/// +/// [The official docs](https://core.telegram.org/bots/api#setgamescore). +/// +/// [`Message`]: crate::types::Message +/// [`True`]: crate::types::True #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SetGameScore<'a> { #[serde(skip_serializing)] bot: &'a Bot, - #[serde(flatten)] chat_or_inline_message: ChatOrInlineMessage, - - /// User identifier user_id: i32, - /// New score, must be non-negative score: i32, - /// Pass True, if the high score is allowed to decrease. This can be useful - /// when fixing mistakes or banning cheaters force: Option, - /// Pass True, if the game message should not be automatically edited to - /// include the current scoreboard disable_edit_message: Option, } @@ -69,21 +68,30 @@ impl<'a> SetGameScore<'a> { self } + /// User identifier. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self } + /// New score, must be non-negative. pub fn score(mut self, val: i32) -> Self { self.score = val; self } + /// Pass `true`, if the high score is allowed to decrease. + /// + /// This can be useful when fixing mistakes or banning cheaters. pub fn force(mut self, val: bool) -> Self { self.force = Some(val); self } + /// Sends the message [silently]. Users will receive a notification with no + /// sound. + /// + /// [silently]: https://telegram.org/blog/channels-2-0#silent-messages pub fn disable_edit_message(mut self, val: bool) -> Self { self.disable_edit_message = Some(val); self diff --git a/src/requests/all/set_sticker_position_in_set.rs b/src/requests/all/set_sticker_position_in_set.rs index b1d4f0e5..48325d70 100644 --- a/src/requests/all/set_sticker_position_in_set.rs +++ b/src/requests/all/set_sticker_position_in_set.rs @@ -8,16 +8,15 @@ use crate::{ }; /// Use this method to move a sticker in a set created by the bot to a specific -/// position . Returns True on success. +/// position. +/// +/// [The official docs](https://core.telegram.org/bots/api#setstickerpositioninset). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SetStickerPositionInSet<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// File identifier of the sticker sticker: String, - /// New sticker position in the set, zero-based position: i32, } @@ -49,6 +48,7 @@ impl<'a> SetStickerPositionInSet<'a> { } } + /// File identifier of the sticker. pub fn sticker(mut self, val: T) -> Self where T: Into, @@ -57,6 +57,7 @@ impl<'a> SetStickerPositionInSet<'a> { self } + /// New sticker position in the set, zero-based. pub fn position(mut self, val: i32) -> Self { self.position = val; self diff --git a/src/requests/all/set_webhook.rs b/src/requests/all/set_webhook.rs index 4dcbb396..5f9ba486 100644 --- a/src/requests/all/set_webhook.rs +++ b/src/requests/all/set_webhook.rs @@ -3,49 +3,33 @@ use serde::Serialize; use crate::{ network, requests::{Request, ResponseResult}, - types::{InputFile, True}, + types::{AllowedUpdate, InputFile, True}, Bot, }; /// Use this method to specify a url and receive incoming updates via an /// outgoing webhook. Whenever there is an update for the bot, we will send an /// HTTPS POST request to the specified url, containing a JSON-serialized -/// Update. In case of an unsuccessful request, we will give up after a -/// reasonable amount of attempts. Returns True on success. If you'd like to -/// make sure that the Webhook request comes from Telegram, we recommend using a secret path in the URL, e.g. https://www.example.com/. Since nobody else -/// knows your bot‘s token, you can be pretty sure it’s us.Notes1. You will not -/// be able to receive updates using getUpdates for as long as an outgoing -/// webhook is set up.2. To use a self-signed certificate, you need to upload -/// your public key certificate using certificate parameter. Please upload as -/// InputFile, sending a String will not work.3. Ports currently supported for -/// Webhooks: 443, 80, 88, 8443.NEW! If you're having any trouble setting up -/// webhooks, please check out this amazing guide to Webhooks. +/// [`Update`]. In case of an unsuccessful request, we will give up after a +/// reasonable amount of attempts. +/// +/// If you'd like to make sure that the Webhook request comes from Telegram, +/// we recommend using a secret path in the URL, e.g. +/// `https://www.example.com/`. Since nobody else knows your bot‘s +/// token, you can be pretty sure it’s us. +/// +/// [The official docs](https://core.telegram.org/bots/api#setwebhook). +/// +/// [`Update`]: crate::types::Update #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct SetWebhook<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// HTTPS url to send updates to. Use an empty string to remove webhook - /// integration url: String, - /// Upload your public key certificate so that the root certificate in use - /// can be checked. See our self-signed guide for details. certificate: Option, - /// Maximum allowed number of simultaneous HTTPS connections to the webhook - /// for update delivery, 1-100. Defaults to 40. Use lower values to limit - /// the load on your bot‘s server, and higher values to increase your bot’s - /// throughput. max_connections: Option, - /// List the types of updates you want your bot to receive. For example, - /// specify [“message”, “edited_channel_post”, “callback_query”] to only - /// receive updates of these types. See Update for a complete list of - /// available update types. Specify an empty list to receive all updates - /// regardless of type (default). If not specified, the previous setting - /// will be used.Please note that this parameter doesn't affect updates - /// created before the call to the setWebhook, so unwanted updates may be - /// received for a short period of time. - allowed_updates: Option>, + allowed_updates: Option>, } #[async_trait::async_trait] @@ -78,6 +62,9 @@ impl<'a> SetWebhook<'a> { } } + /// HTTPS url to send updates to. + /// + /// Use an empty string to remove webhook integration. pub fn url(mut self, val: T) -> Self where T: Into, @@ -86,19 +73,50 @@ impl<'a> SetWebhook<'a> { self } + /// Upload your public key certificate so that the root certificate in use + /// can be checked. + /// + /// See our [self-signed guide] for details. + /// + /// [self-signed guide]: https://core.telegram.org/bots/self-signed pub fn certificate(mut self, val: InputFile) -> Self { self.certificate = Some(val); self } + /// Maximum allowed number of simultaneous HTTPS connections to the webhook + /// for update delivery, 1-100. + /// + /// Defaults to 40. Use lower values to limit the load on your bot‘s server, + /// and higher values to increase your bot’s throughput. pub fn max_connections(mut self, val: i32) -> Self { self.max_connections = Some(val); self } + /// List the types of updates you want your bot to receive. + /// + /// For example, specify [`AllowedUpdate::Message`], + /// [`AllowedUpdate::EditedChannelPost`], [`AllowedUpdate::CallbackQuery`] + /// to only receive updates of these types. Specify an empty list to receive + /// all updates regardless of type (default). If not specified, the + /// previous setting will be used. See [`AllowedUpdate`] for a complete list + /// of available update types. + /// + /// Please note that this parameter doesn't affect updates created before + /// the call to the [`Bot::set_webhook`], so unwanted updates may be + /// received for a short period of time. + /// + /// [`Bot::set_webhook`]: crate::Bot::set_webhook + /// [`AllowedUpdate::Message`]: crate::types::AllowedUpdate::Message + /// [`AllowedUpdate::EditedChannelPost`]: + /// crate::types::AllowedUpdate::EditedChannelPost + /// [`AllowedUpdate::CallbackQuery`]: + /// crate::types::AllowedUpdate::CallbackQuery + /// [`AllowedUpdate`]: crate::types::AllowedUpdate pub fn allowed_updates(mut self, val: T) -> Self where - T: Into>, + T: Into>, { self.allowed_updates = Some(val.into()); self diff --git a/src/requests/all/stop_message_live_location.rs b/src/requests/all/stop_message_live_location.rs index ea2c544b..4353e672 100644 --- a/src/requests/all/stop_message_live_location.rs +++ b/src/requests/all/stop_message_live_location.rs @@ -7,19 +7,23 @@ use crate::{ Bot, }; -/// Use this method to stop updating a live location message before live_period -/// expires. On success, if the message was sent by the bot, the sent Message is -/// returned, otherwise True is returned. +/// Use this method to stop updating a live location message before +/// `live_period` expires. +/// +/// On success, if the message was sent by the bot, the sent [`Message`] is +/// returned, otherwise [`True`] is returned. +/// +/// [The official docs](https://core.telegram.org/bots/api#stopmessagelivelocation). +/// +/// [`Message`]: crate::types::Message +/// [`True`]: crate::types::True #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct StopMessageLiveLocation<'a> { #[serde(skip_serializing)] bot: &'a Bot, - #[serde(flatten)] chat_or_inline_message: ChatOrInlineMessage, - - /// A JSON-serialized object for a new inline keyboard. reply_markup: Option, } @@ -55,6 +59,9 @@ impl<'a> StopMessageLiveLocation<'a> { self } + /// A JSON-serialized object for a new [inline keyboard]. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating pub fn reply_markup(mut self, val: InlineKeyboardMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/stop_poll.rs b/src/requests/all/stop_poll.rs index 9590f142..edfa892c 100644 --- a/src/requests/all/stop_poll.rs +++ b/src/requests/all/stop_poll.rs @@ -7,20 +7,16 @@ use crate::{ Bot, }; -/// Use this method to stop a poll which was sent by the bot. On success, the -/// stopped Poll with the final results is returned. +/// Use this method to stop a poll which was sent by the bot. +/// +/// [The official docs](https://core.telegram.org/bots/api#stoppoll). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct StopPoll<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, - /// Identifier of the original message with the poll message_id: i32, - /// A JSON-serialized object for a new message inline keyboard. reply_markup: Option, } @@ -28,6 +24,9 @@ pub struct StopPoll<'a> { impl Request for StopPoll<'_> { type Output = Poll; + /// On success, the stopped [`Poll`] with the final results is returned. + /// + /// [`Poll`]: crate::types::Poll async fn send(&self) -> ResponseResult { network::request_json( self.bot.client(), @@ -52,6 +51,8 @@ impl<'a> StopPoll<'a> { } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -60,11 +61,15 @@ impl<'a> StopPoll<'a> { self } + /// Identifier of the original message with the poll. pub fn message_id(mut self, val: i32) -> Self { self.message_id = val; self } + /// A JSON-serialized object for a new [inline keyboard]. + /// + /// [inline keyboard]: https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating pub fn reply_markup(mut self, val: InlineKeyboardMarkup) -> Self { self.reply_markup = Some(val); self diff --git a/src/requests/all/unban_chat_member.rs b/src/requests/all/unban_chat_member.rs index 9b3ccb7f..d9114aed 100644 --- a/src/requests/all/unban_chat_member.rs +++ b/src/requests/all/unban_chat_member.rs @@ -8,19 +8,17 @@ use crate::{ }; /// Use this method to unban a previously kicked user in a supergroup or -/// channel. The user will not return to the group or channel automatically, but -/// will be able to join via link, etc. The bot must be an administrator for -/// this to work. Returns True on success. +/// channel. The user will **not** return to the group or channel automatically, +/// but will be able to join via link, etc. The bot must be an administrator for +/// this to work. +/// +/// [The official docs](https://core.telegram.org/bots/api#unbanchatmember). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct UnbanChatMember<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target group or username of the target - /// supergroup or channel (in the format @username) chat_id: ChatId, - /// Unique identifier of the target user user_id: i32, } @@ -52,6 +50,8 @@ impl<'a> UnbanChatMember<'a> { } } + /// Unique identifier for the target group or username of the target + /// supergroup or channel (in the format `@username`). pub fn chat_id(mut self, val: T) -> Self where T: Into, @@ -60,6 +60,7 @@ impl<'a> UnbanChatMember<'a> { self } + /// Unique identifier of the target user. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self diff --git a/src/requests/all/unpin_chat_message.rs b/src/requests/all/unpin_chat_message.rs index 7a93c890..ca198f97 100644 --- a/src/requests/all/unpin_chat_message.rs +++ b/src/requests/all/unpin_chat_message.rs @@ -9,16 +9,15 @@ use crate::{ /// Use this method to unpin a message in a group, a supergroup, or a channel. /// The bot must be an administrator in the chat for this to work and must have -/// the ‘can_pin_messages’ admin right in the supergroup or ‘can_edit_messages’ -/// admin right in the channel. Returns True on success. +/// the `can_pin_messages` admin right in the supergroup or `can_edit_messages` +/// admin right in the channel. +/// +/// [The official docs](https://core.telegram.org/bots/api#unpinchatmessage). #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct UnpinChatMessage<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// Unique identifier for the target chat or username of the target channel - /// (in the format @channelusername) chat_id: ChatId, } @@ -46,6 +45,8 @@ impl<'a> UnpinChatMessage<'a> { Self { bot, chat_id } } + /// Unique identifier for the target chat or username of the target channel + /// (in the format `@channelusername`). pub fn chat_id(mut self, val: T) -> Self where T: Into, diff --git a/src/requests/all/upload_sticker_file.rs b/src/requests/all/upload_sticker_file.rs index ba34abd5..dc11c94e 100644 --- a/src/requests/all/upload_sticker_file.rs +++ b/src/requests/all/upload_sticker_file.rs @@ -8,19 +8,19 @@ use crate::{ }; /// Use this method to upload a .png file with a sticker for later use in -/// createNewStickerSet and addStickerToSet methods (can be used multiple -/// times). Returns the uploaded File on success. +/// [`Bot::create_new_sticker_set`] and [`Bot::add_sticker_to_set`] methods (can +/// be used multiple times). +/// +/// [The official docs](https://core.telegram.org/bots/api#uploadstickerfile). +/// +/// [`Bot::create_new_sticker_set`]: crate::Bot::create_new_sticker_set +/// [`Bot::add_sticker_to_set`]: crate::Bot::add_sticker_to_set #[serde_with_macros::skip_serializing_none] #[derive(Debug, Clone, Serialize)] pub struct UploadStickerFile<'a> { #[serde(skip_serializing)] bot: &'a Bot, - - /// User identifier of sticker file owner user_id: i32, - /// Png image with the sticker, must be up to 512 kilobytes in size, - /// dimensions must not exceed 512px, and either width or height must be - /// exactly 512px. More info on Sending Files » png_sticker: InputFile, } #[async_trait::async_trait] @@ -51,11 +51,17 @@ impl<'a> UploadStickerFile<'a> { } } + /// User identifier of sticker file owner. pub fn user_id(mut self, val: i32) -> Self { self.user_id = val; self } + /// **Png** image with the sticker, must be up to 512 kilobytes in size, + /// dimensions must not exceed 512px, and either width or height must be + /// exactly 512px. [More info on Sending Files »]. + /// + /// [More info on Sending Files »]: https://core.telegram.org/bots/api#sending-files pub fn png_sticker(mut self, val: InputFile) -> Self { self.png_sticker = val; self