Improve documentation and code comments

CHANGELOG.md

@@ -8,19 +8,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Add `filter_boost_added` and `filter_reply_to_story` filters to `MessageFilterExt` trait
+- `filter_boost_added` and `filter_reply_to_story` filters to the `MessageFilterExt` trait ([PR 1131](https://github.com/teloxide/teloxide/pull/1131))
-- Add `filter_mention_command` filter to `HandlerExt` trait ([issue #494](https://github.com/teloxide/teloxide/issues/494))
+- `filter_mention_command` filter to the `HandlerExt` trait ([issue 494](https://github.com/teloxide/teloxide/issues/494))
-- Add `filter_business_connection`, `filter_business_message`, `filter_edited_business_message`, and `filter_deleted_business_messages` filters to update filters ([PR 1146](https://github.com/teloxide/teloxide/pull/1146))
+- `filter_business_connection`, `filter_business_message`, `filter_edited_business_message`, and `filter_deleted_business_messages` filters to the `UpdateFilterExt` trait ([PR 1146](https://github.com/teloxide/teloxide/pull/1146))
-- Add `Render` util to recreate rendered Html or Markdown formatted text from text/caption and `MessageEntity` ([PR 1152](https://github.com/teloxide/teloxide/pull/1152))
+- Syntax sugar for making requests ([issue 1143](https://github.com/teloxide/teloxide/issues/1143)):
+  - `bot.forward`, `bot.edit_live_location`, `bot.stop_live_location`, `bot.set_reaction`, `bot.pin`, `bot.unpin`, `bot.edit_text`, `bot.edit_caption`, `bot.edit_media`, `bot.edit_reply_markup`, `bot.stop_poll_message`, `bot.delete` and `bot.copy` methods to the new `crate::sugar::bot::BotMessagesExt` trait
+  - `req.reply_to` method to the new `crate::sugar::request::RequestReplyExt` trait
+  - `req.disable_link_preview` method to the new `crate::sugar::request::RequestLinkPreviewExt` trait
+- Add `Render` utilities  to recreate rendered Html or Markdown formatted text from text/caption and a list of `MessageEntity` ([PR 1152](https://github.com/teloxide/teloxide/pull/1152))
 
 ### Changed
 
-- Environment bumps: ([#1147][pr1147])
+- Environment bumps: ([PR 1147](https://github.com/teloxide/teloxide/pull/1147))
   - MSRV (Minimal Supported Rust Version) was bumped from `1.70.0` to `1.80.0`
   - Some dependencies was bumped: `sqlx` to `0.8.1`, `tower` to `0.5.0`, `reqwest` to `0.12.7`
   - `tokio` version was explicitly specified as `1.39`
 
-[pr1147]: https://github.com/teloxide/teloxide/pull/1147
+### Fixed
+
+- Now Vec<MessageId> in requests serializes into [number] instead of [ {message_id: number} ], `forward_messages`, `copy_messages` and `delete_messages` now work properly
+- Now `InlineQueryResultsButton` serializes properly ([issue 1181](https://github.com/teloxide/teloxide/issues/1181))
+- Now `ThreadId` is able to serialize in multipart requests ([PR 1179](https://github.com/teloxide/teloxide/pull/1179))
 
 ## 0.13.0 - 2024-08-16
 

crates/teloxide-core/src/types/keyboard_button_request_chat.rs

@@ -4,7 +4,6 @@ use crate::types::{ChatAdministratorRights, RequestId};
 
 /// This object defines the criteria used to request a suitable chat.
 ///
-///
 /// Information about the selected chat will be shared with the bot when the
 /// corresponding button is pressed. The bot will be granted requested rights in
 /// the chat if appropriate. [More about requesting chats »]

crates/teloxide-core/src/types/keyboard_button_request_users.rs

@@ -4,7 +4,6 @@ use crate::types::RequestId;
 
 /// This object defines the criteria used to request a suitable users.
 ///
-///
 /// Information about the selected users will be shared with the bot when the
 /// corresponding button is pressed. More about requesting users »
 ///

crates/teloxide/src/utils/render/helper.rs

@@ -1,5 +1,5 @@
-//! A helprt trait for rendering text/caption and entities back to html or
+//! A helpful trait for rendering text/caption and entities back to HTML or
-//! markdown
+//! Markdown.
 
 use teloxide_core::types::Message;
 
@@ -14,18 +14,21 @@ pub trait RenderMessageTextHelper {
     /// string.
     #[must_use]
     fn html_text(&self) -> Option<String>;
+
     /// Returns the Markdown representation of the message text, if the message
     /// contains text. This method will parse the text and any entities
     /// (such as bold, italic, links, etc.) and return the
     /// Markdown-formatted string.
     #[must_use]
     fn markdown_text(&self) -> Option<String>;
+
     /// Returns the HTML representation of the message caption, if the message
     /// contains caption. This method will parse the caption and any
     /// entities (such as bold, italic, links, etc.) and return the
     /// HTML-formatted string.
     #[must_use]
     fn html_caption(&self) -> Option<String>;
+
     /// Returns the Markdown representation of the message caption, if the
     /// message contains caption. This method will parse the caption and any
     /// entities (such as bold, italic, links, etc.) and return the

crates/teloxide/src/utils/render/html.rs

@@ -15,7 +15,6 @@ pub static HTML: TagWriter = TagWriter {
     text_link: ComplexTag::new("<a href=\"", "\">", "</a>"),
     text_mention: ComplexTag::new("<a href=\"tg://user?id=", "\">", "</a>"),
     custom_emoji: ComplexTag::new("<tg-emoji emoji-id=\"", "\">", "</tg-emoji>"),
-
     write_tag_fn: write_tag,
     write_char_fn: write_char,
 };

crates/teloxide/src/utils/render/markdown.rs

@@ -17,7 +17,6 @@ pub static MARKDOWN: TagWriter = TagWriter {
     text_link: ComplexTag::new("[", "](", ")"),
     text_mention: ComplexTag::new("[", "](tg://user?id=", ")"),
     custom_emoji: ComplexTag::new("[", "](tg://emoji?id=", ")"),
-
     write_tag_fn: write_tag,
     write_char_fn: write_char,
 };

crates/teloxide/src/utils/render/mod.rs

@@ -1,4 +1,4 @@
-//! Util for rendering texts and message entities to html and markdown string
+//! Utilities for rendering texts and message entities to HTML and Markdown.
 
 use teloxide_core::types::{MessageEntity, MessageEntityKind as MEK};
 
@@ -31,10 +31,6 @@ impl<'a> Render<'a> {
     /// - `text`: The input text to be parsed.
     /// - `entities`: The message entities (formatting, links, etc.) to be
     ///   applied to the text.
-    ///
-    /// # Returns
-    ///
-    /// A new [`Render`] instance.
     #[must_use]
     pub fn new(text: &'a str, entities: &'a [MessageEntity]) -> Self {
         // get the needed size for the new tags that we want to parse from entities
@@ -57,7 +53,7 @@ impl<'a> Render<'a> {
                 )
             })
             .count()
-            * 2; // 2 because we inseret two tag for each entity
+            * 2; // 2 because we insert two tags for each entity
 
         let mut tags = Vec::with_capacity(needed_size);
 
@@ -101,7 +97,8 @@ impl<'a> Render<'a> {
             return self.text.to_owned();
         }
 
-        let mut buffer = String::with_capacity(self.text.len() + writer.get_tags_sizes(&self.tags));
+        let mut buffer =
+            String::with_capacity(self.text.len() + writer.get_extra_size_for_tags(&self.tags));
         let mut tags = self.tags.iter();
         let mut current_tag = tags.next();
 
@@ -140,14 +137,14 @@ impl<'a> Render<'a> {
         buffer
     }
 
-    /// Render and return the text as **Html-formatted** string.
+    /// Render and return the text as an **HTML-formatted** string.
     #[must_use]
     #[inline]
     pub fn as_html(&self) -> String {
         self.format(&html::HTML)
     }
 
-    /// Render and return the text as **Markdown-formatted** string.
+    /// Render and return the text as a **Markdown-formatted** string.
     #[must_use]
     #[inline]
     pub fn as_markdown(&self) -> String {

crates/teloxide/src/utils/render/tag.rs

@@ -81,7 +81,6 @@ impl SimpleTag {
         Self { start, end }
     }
 
-    /// Get tag size based on place
     pub const fn get_tag(&self, place: Place) -> &'static str {
         match place {
             Place::Start => self.start,
@@ -116,16 +115,12 @@ pub struct TagWriter {
     pub text_link: ComplexTag,
     pub text_mention: ComplexTag,
     pub custom_emoji: ComplexTag,
-
-    /// Write the tag to buffer
     pub write_tag_fn: fn(&Tag, buf: &mut String),
-    /// Write the char to buffer and escape characters if needed
     pub write_char_fn: fn(char, buf: &mut String),
 }
 
 impl TagWriter {
-    /// Get the extra size needed for tags
+    pub fn get_extra_size_for_tags(&self, tags: &[Tag]) -> usize {
-    pub fn get_tags_sizes(&self, tags: &[Tag]) -> usize {
         tags.iter()
             .map(|tag| match tag.kind {
                 Kind::Bold => self.bold.get_tag(tag.place).len(),