docs: complete rustdoc documentation for all public APIs (P4.12)
Added comprehensive rustdoc documentation for all TDLib modules, configuration, and utility functions. TDLib modules documented: - src/tdlib/auth.rs - AuthManager, AuthState (6 doctests) - src/tdlib/chats.rs - ChatManager (8 doctests) - src/tdlib/messages.rs - MessageManager (14 methods, 6 doctests) - src/tdlib/reactions.rs - ReactionManager (3 doctests) - src/tdlib/users.rs - UserCache, LruCache (2 doctests) Configuration and utilities: - src/config.rs - Config, ColorsConfig, GeneralConfig (4 doctests) - src/formatting.rs - format_text_with_entities (2 doctests) Documentation includes: - Detailed descriptions of all public structs and methods - Usage examples with code snippets - Parameter and return value documentation - Notes about async behavior and edge cases - Cross-references between related functions Total: 34 doctests (30 ignored for async, 4 compiled) All 464 unit tests passing ✅ Priority 4.12 (Rustdoc) - 100% complete Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Mikhail Kilin
@@ -6,17 +6,65 @@ use tdlib_rs::types::{Chat as TdChat, FormattedText, InputMessageReplyToMessage,
|
||||
|
||||
use super::types::{ForwardInfo, MessageBuilder, MessageInfo, ReactionInfo, ReplyInfo};
|
||||
|
||||
/// Менеджер сообщений
|
||||
/// Менеджер сообщений TDLib.
|
||||
///
|
||||
/// Управляет загрузкой, отправкой, редактированием и удалением сообщений.
|
||||
/// Кеширует сообщения текущего открытого чата и закрепленные сообщения.
|
||||
///
|
||||
/// # Основные возможности
|
||||
///
|
||||
/// - Загрузка истории сообщений чата
|
||||
/// - Отправка текстовых сообщений с поддержкой Markdown
|
||||
/// - Редактирование и удаление сообщений
|
||||
/// - Пересылка сообщений между чатами
|
||||
/// - Поиск сообщений по тексту
|
||||
/// - Управление закрепленными сообщениями
|
||||
/// - Управление черновиками
|
||||
/// - Автоматическая отметка сообщений как прочитанных
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```ignore
|
||||
/// let mut msg_manager = MessageManager::new(client_id);
|
||||
///
|
||||
/// // Загрузить историю чата
|
||||
/// let messages = msg_manager.get_chat_history(chat_id, 50).await?;
|
||||
///
|
||||
/// // Отправить сообщение
|
||||
/// let msg = msg_manager.send_message(
|
||||
/// chat_id,
|
||||
/// "Hello, **world**!".to_string(),
|
||||
/// None,
|
||||
/// None
|
||||
/// ).await?;
|
||||
/// ```
|
||||
pub struct MessageManager {
|
||||
/// Список сообщений текущего открытого чата (до MAX_MESSAGES_IN_CHAT).
|
||||
pub current_chat_messages: Vec<MessageInfo>,
|
||||
|
||||
/// ID текущего открытого чата.
|
||||
pub current_chat_id: Option<ChatId>,
|
||||
|
||||
/// Текущее закрепленное сообщение открытого чата.
|
||||
pub current_pinned_message: Option<MessageInfo>,
|
||||
/// Очередь сообщений для отметки как прочитанных: (chat_id, message_ids)
|
||||
|
||||
/// Очередь сообщений для отметки как прочитанных: (chat_id, message_ids).
|
||||
pub pending_view_messages: Vec<(ChatId, Vec<MessageId>)>,
|
||||
|
||||
/// ID клиента TDLib для API вызовов.
|
||||
client_id: i32,
|
||||
}
|
||||
|
||||
impl MessageManager {
|
||||
/// Создает новый менеджер сообщений.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `client_id` - ID клиента TDLib для API вызовов
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// Новый экземпляр `MessageManager` с пустым списком сообщений.
|
||||
pub fn new(client_id: i32) -> Self {
|
||||
Self {
|
||||
current_chat_messages: Vec::new(),
|
||||
@@ -27,7 +75,19 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Добавить сообщение в список текущего чата
|
||||
/// Добавляет сообщение в список текущего чата.
|
||||
///
|
||||
/// Автоматически ограничивает размер списка до [`MAX_MESSAGES_IN_CHAT`],
|
||||
/// удаляя старые сообщения при превышении лимита.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `msg` - Сообщение для добавления
|
||||
///
|
||||
/// # Note
|
||||
///
|
||||
/// Сообщение добавляется в конец списка. При превышении лимита
|
||||
/// удаляются самые старые сообщения из начала списка.
|
||||
pub fn push_message(&mut self, msg: MessageInfo) {
|
||||
self.current_chat_messages.push(msg); // Добавляем в конец
|
||||
|
||||
@@ -37,7 +97,31 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Получить историю чата
|
||||
/// Загружает историю сообщений чата.
|
||||
///
|
||||
/// Запрашивает последние сообщения из указанного чата и сохраняет их
|
||||
/// в [`current_chat_messages`](Self::current_chat_messages). Делает несколько попыток
|
||||
/// загрузки при неудаче.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `chat_id` - ID чата для загрузки истории
|
||||
/// * `limit` - Максимальное количество сообщений (обычно до 50)
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// * `Ok(Vec<MessageInfo>)` - Список загруженных сообщений (от старых к новым)
|
||||
/// * `Err(String)` - Ошибка загрузки после всех попыток
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```ignore
|
||||
/// let messages = msg_manager.get_chat_history(
|
||||
/// ChatId::new(123),
|
||||
/// 50
|
||||
/// ).await?;
|
||||
/// println!("Loaded {} messages", messages.len());
|
||||
/// ```
|
||||
pub async fn get_chat_history(
|
||||
&mut self,
|
||||
chat_id: ChatId,
|
||||
@@ -102,7 +186,30 @@ impl MessageManager {
|
||||
Ok(all_messages)
|
||||
}
|
||||
|
||||
/// Загрузить более старые сообщения
|
||||
/// Загружает более старые сообщения для пагинации.
|
||||
///
|
||||
/// Используется для подгрузки предыдущих сообщений при прокрутке
|
||||
/// истории чата вверх.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `chat_id` - ID чата
|
||||
/// * `from_message_id` - ID сообщения, от которого загружать историю
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// * `Ok(Vec<MessageInfo>)` - Список старых сообщений (от старых к новым)
|
||||
/// * `Err(String)` - Ошибка загрузки
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```ignore
|
||||
/// // Загрузить сообщения старше указанного
|
||||
/// let older = msg_manager.load_older_messages(
|
||||
/// chat_id,
|
||||
/// MessageId::new(12345)
|
||||
/// ).await?;
|
||||
/// ```
|
||||
pub async fn load_older_messages(
|
||||
&mut self,
|
||||
chat_id: ChatId,
|
||||
@@ -135,7 +242,25 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Получить закреплённые сообщения
|
||||
/// Получает все закрепленные сообщения чата.
|
||||
///
|
||||
/// Выполняет поиск всех сообщений с фильтром "pinned" и возвращает их список.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `chat_id` - ID чата
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// * `Ok(Vec<MessageInfo>)` - Список закрепленных сообщений (до 100)
|
||||
/// * `Err(String)` - Ошибка загрузки
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```ignore
|
||||
/// let pinned = msg_manager.get_pinned_messages(chat_id).await?;
|
||||
/// println!("Found {} pinned messages", pinned.len());
|
||||
/// ```
|
||||
pub async fn get_pinned_messages(&mut self, chat_id: ChatId) -> Result<Vec<MessageInfo>, String> {
|
||||
let result = functions::search_chat_messages(
|
||||
chat_id.as_i64(),
|
||||
@@ -166,7 +291,17 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Загрузить текущее закреплённое сообщение
|
||||
/// Загружает текущее верхнее закрепленное сообщение.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `chat_id` - ID чата
|
||||
///
|
||||
/// # Note
|
||||
///
|
||||
/// TODO: В tdlib-rs 1.8.29 поле `pinned_message_id` было удалено из `Chat`.
|
||||
/// Нужно использовать `getChatPinnedMessage` или альтернативный способ.
|
||||
/// Временно отключено, возвращает `None`.
|
||||
pub async fn load_current_pinned_message(&mut self, chat_id: ChatId) {
|
||||
// TODO: В tdlib-rs 1.8.29 поле pinned_message_id было удалено из Chat.
|
||||
// Нужно использовать getChatPinnedMessage или альтернативный способ.
|
||||
@@ -182,7 +317,23 @@ impl MessageManager {
|
||||
// }
|
||||
}
|
||||
|
||||
/// Поиск сообщений в чате
|
||||
/// Выполняет поиск сообщений по тексту в указанном чате.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `chat_id` - ID чата для поиска
|
||||
/// * `query` - Текстовый запрос для поиска
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// * `Ok(Vec<MessageInfo>)` - Найденные сообщения (до 100)
|
||||
/// * `Err(String)` - Ошибка поиска
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```ignore
|
||||
/// let results = msg_manager.search_messages(chat_id, "hello").await?;
|
||||
/// ```
|
||||
pub async fn search_messages(
|
||||
&self,
|
||||
chat_id: ChatId,
|
||||
@@ -217,7 +368,41 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Отправить сообщение
|
||||
/// Отправляет текстовое сообщение в чат с поддержкой Markdown.
|
||||
///
|
||||
/// Автоматически парсит Markdown v2 форматирование (**bold**, *italic*, `code` и т.д.).
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `chat_id` - ID чата-получателя
|
||||
/// * `text` - Текст сообщения (поддерживает Markdown v2)
|
||||
/// * `reply_to_message_id` - Опциональный ID сообщения для ответа
|
||||
/// * `reply_info` - Опциональная информация об исходном сообщении
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// * `Ok(MessageInfo)` - Отправленное сообщение
|
||||
/// * `Err(String)` - Ошибка отправки
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```ignore
|
||||
/// // Простое сообщение
|
||||
/// let msg = msg_manager.send_message(
|
||||
/// chat_id,
|
||||
/// "Hello, **world**!".to_string(),
|
||||
/// None,
|
||||
/// None
|
||||
/// ).await?;
|
||||
///
|
||||
/// // Ответ на сообщение
|
||||
/// let reply = msg_manager.send_message(
|
||||
/// chat_id,
|
||||
/// "Got it!".to_string(),
|
||||
/// Some(MessageId::new(123)),
|
||||
/// Some(reply_info)
|
||||
/// ).await?;
|
||||
/// ```
|
||||
pub async fn send_message(
|
||||
&self,
|
||||
chat_id: ChatId,
|
||||
@@ -288,7 +473,18 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Редактировать сообщение
|
||||
/// Редактирует существующее сообщение.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `chat_id` - ID чата
|
||||
/// * `message_id` - ID сообщения для редактирования
|
||||
/// * `text` - Новый текст (поддерживает Markdown v2)
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// * `Ok(MessageInfo)` - Отредактированное сообщение
|
||||
/// * `Err(String)` - Ошибка (нет прав, сообщение слишком старое и т.д.)
|
||||
pub async fn edit_message(
|
||||
&self,
|
||||
chat_id: ChatId,
|
||||
@@ -333,7 +529,18 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Удалить сообщения
|
||||
/// Удаляет одно или несколько сообщений.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `chat_id` - ID чата
|
||||
/// * `message_ids` - Список ID сообщений для удаления
|
||||
/// * `revoke` - `true` - удалить для всех, `false` - только для себя
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// * `Ok(())` - Сообщения удалены
|
||||
/// * `Err(String)` - Ошибка удаления
|
||||
pub async fn delete_messages(
|
||||
&self,
|
||||
chat_id: ChatId,
|
||||
@@ -349,7 +556,18 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Переслать сообщения
|
||||
/// Пересылает сообщения из одного чата в другой.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `to_chat_id` - ID чата-получателя
|
||||
/// * `from_chat_id` - ID чата-источника
|
||||
/// * `message_ids` - Список ID сообщений для пересылки
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// * `Ok(())` - Сообщения переслань
|
||||
/// * `Err(String)` - Ошибка пересылки
|
||||
pub async fn forward_messages(
|
||||
&self,
|
||||
to_chat_id: ChatId,
|
||||
@@ -375,7 +593,20 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Установить черновик
|
||||
/// Сохраняет черновик сообщения для чата.
|
||||
///
|
||||
/// Черновик отображается в списке чатов и восстанавливается
|
||||
/// при следующем открытии чата.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `chat_id` - ID чата
|
||||
/// * `text` - Текст черновика (пустая строка удаляет черновик)
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// * `Ok(())` - Черновик сохранен
|
||||
/// * `Err(String)` - Ошибка сохранения
|
||||
pub async fn set_draft_message(&self, chat_id: ChatId, text: String) -> Result<(), String> {
|
||||
use tdlib_rs::types::DraftMessage;
|
||||
|
||||
@@ -404,7 +635,14 @@ impl MessageManager {
|
||||
}
|
||||
}
|
||||
|
||||
/// Обработать очередь просмотра сообщений
|
||||
/// Обрабатывает очередь сообщений для отметки как прочитанных.
|
||||
///
|
||||
/// Автоматически отмечает просмотренные сообщения как прочитанные,
|
||||
/// что сбрасывает счетчик непрочитанных сообщений в чате.
|
||||
///
|
||||
/// # Note
|
||||
///
|
||||
/// Вызывайте периодически (например, в основном цикле) для обработки накопленной очереди.
|
||||
pub async fn process_pending_view_messages(&mut self) {
|
||||
if self.pending_view_messages.is_empty() {
|
||||
return;
|
||||
@@ -571,7 +809,14 @@ impl MessageManager {
|
||||
Some(builder.build())
|
||||
}
|
||||
|
||||
/// Получить недостающую reply информацию для сообщений
|
||||
/// Загружает недостающую информацию об исходных сообщениях для ответов.
|
||||
///
|
||||
/// Ищет все reply-сообщения с `sender_name == "Unknown"` и загружает
|
||||
/// полную информацию (имя отправителя, текст) из TDLib.
|
||||
///
|
||||
/// # Note
|
||||
///
|
||||
/// Вызывайте после загрузки истории чата для заполнения информации о цитируемых сообщениях.
|
||||
pub async fn fetch_missing_reply_info(&mut self) {
|
||||
// Collect message IDs that need to be fetched
|
||||
let mut to_fetch = Vec::new();
|
||||
|
||||
Reference in New Issue
Block a user