Improve documentation and code comments

This commit is contained in:
YouKnow 2024-10-20 02:26:18 +03:30
parent e96139634d
commit adb9830c93
8 changed files with 27 additions and 28 deletions

View file

@ -8,19 +8,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added ### 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 ### 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` - 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` - 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` - `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 ## 0.13.0 - 2024-08-16

View file

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

View file

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

View file

@ -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; use teloxide_core::types::Message;
@ -14,18 +14,21 @@ pub trait RenderMessageTextHelper {
/// string. /// string.
#[must_use] #[must_use]
fn html_text(&self) -> Option<String>; fn html_text(&self) -> Option<String>;
/// Returns the Markdown representation of the message text, if the message /// Returns the Markdown representation of the message text, if the message
/// contains text. This method will parse the text and any entities /// contains text. This method will parse the text and any entities
/// (such as bold, italic, links, etc.) and return the /// (such as bold, italic, links, etc.) and return the
/// Markdown-formatted string. /// Markdown-formatted string.
#[must_use] #[must_use]
fn markdown_text(&self) -> Option<String>; fn markdown_text(&self) -> Option<String>;
/// Returns the HTML representation of the message caption, if the message /// Returns the HTML representation of the message caption, if the message
/// contains caption. This method will parse the caption and any /// contains caption. This method will parse the caption and any
/// entities (such as bold, italic, links, etc.) and return the /// entities (such as bold, italic, links, etc.) and return the
/// HTML-formatted string. /// HTML-formatted string.
#[must_use] #[must_use]
fn html_caption(&self) -> Option<String>; fn html_caption(&self) -> Option<String>;
/// Returns the Markdown representation of the message caption, if the /// Returns the Markdown representation of the message caption, if the
/// message contains caption. This method will parse the caption and any /// message contains caption. This method will parse the caption and any
/// entities (such as bold, italic, links, etc.) and return the /// entities (such as bold, italic, links, etc.) and return the

View file

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

View file

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

View file

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

View file

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