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>
2026-02-01 01:03:30 +03:00
parent 326bf6cc46
commit 93e43a59d0
7 changed files with 901 additions and 57 deletions
--- a/src/tdlib/auth.rs
+++ b/src/tdlib/auth.rs
@@ -1,25 +1,88 @@
 use tdlib_rs::enums::{AuthorizationState, Update};
 use tdlib_rs::functions;

+/// Состояние процесса авторизации в Telegram.
+///
+/// Отслеживает текущий этап аутентификации пользователя,
+/// от инициализации TDLib до полной авторизации.
 #[derive(Debug, Clone, PartialEq)]
 #[allow(dead_code)]
 pub enum AuthState {
+    /// Ожидание параметров TDLib (начальное состояние).
    WaitTdlibParameters,
+
+    /// Ожидание ввода номера телефона.
    WaitPhoneNumber,
+
+    /// Ожидание ввода кода подтверждения из SMS/Telegram.
    WaitCode,
+
+    /// Ожидание ввода пароля двухфакторной аутентификации (2FA).
    WaitPassword,
+
+    /// Авторизация завершена, клиент готов к работе.
    Ready,
+
+    /// Соединение закрыто.
    Closed,
+
+    /// Произошла ошибка авторизации.
    Error(String),
 }

-/// Менеджер авторизации TDLib
+/// Менеджер авторизации TDLib.
+///
+/// Управляет процессом авторизации пользователя в Telegram,
+/// отслеживает текущее состояние и предоставляет методы
+/// для отправки учетных данных (номер телефона, код, пароль).
+///
+/// # Процесс авторизации
+///
+/// 1. `WaitTdlibParameters` → автоматически
+/// 2. `WaitPhoneNumber` → [`send_phone_number()`](Self::send_phone_number)
+/// 3. `WaitCode` → [`send_code()`](Self::send_code)
+/// 4. `WaitPassword` (опционально) → [`send_password()`](Self::send_password)
+/// 5. `Ready` → авторизация завершена
+///
+/// # Examples
+///
+/// ```ignore
+/// let mut auth_manager = AuthManager::new(client_id);
+///
+/// // Отправляем номер телефона
+/// auth_manager.send_phone_number("+1234567890".to_string()).await?;
+///
+/// // После получения кода из SMS
+/// auth_manager.send_code("12345".to_string()).await?;
+///
+/// // Если включена 2FA
+/// if auth_manager.state == AuthState::WaitPassword {
+///     auth_manager.send_password("my_password".to_string()).await?;
+/// }
+///
+/// // Проверяем авторизацию
+/// if auth_manager.is_authenticated() {
+///     println!("Successfully authenticated!");
+/// }
+/// ```
 pub struct AuthManager {
+    /// Текущее состояние авторизации.
    pub state: AuthState,
+
+    /// ID клиента TDLib для API вызовов.
    client_id: i32,
 }

 impl AuthManager {
+    /// Создает новый менеджер авторизации.
+    ///
+    /// # Arguments
+    ///
+    /// * `client_id` - ID клиента TDLib для API вызовов
+    ///
+    /// # Returns
+    ///
+    /// Новый экземпляр `AuthManager` в состоянии `WaitTdlibParameters`.
    pub fn new(client_id: i32) -> Self {
        Self {
            state: AuthState::WaitTdlibParameters,
@@ -27,11 +90,36 @@ impl AuthManager {
        }
    }

+    /// Проверяет, завершена ли авторизация.
+    ///
+    /// # Returns
+    ///
+    /// `true` если состояние равно `AuthState::Ready`, иначе `false`.
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// if auth_manager.is_authenticated() {
+    ///     println!("User is authenticated");
+    /// }
+    /// ```
    pub fn is_authenticated(&self) -> bool {
        self.state == AuthState::Ready
    }

-    /// Обработать обновление авторизации
+    /// Обрабатывает обновление состояния авторизации от TDLib.
+    ///
+    /// Автоматически обновляет внутреннее состояние [`AuthState`] на основе
+    /// полученного update от TDLib.
+    ///
+    /// # Arguments
+    ///
+    /// * `update` - Обновление от TDLib (проверяется на `Update::AuthorizationState`)
+    ///
+    /// # Note
+    ///
+    /// Этот метод должен вызываться для каждого update от TDLib,
+    /// чтобы состояние авторизации оставалось актуальным.
    pub fn handle_auth_update(&mut self, update: &Update) {
        if let Update::AuthorizationState(auth_update) = update {
            self.state = match &auth_update.authorization_state {
@@ -46,7 +134,25 @@ impl AuthManager {
        }
    }

-    /// Отправить номер телефона
+    /// Отправляет номер телефона для авторизации.
+    ///
+    /// Используется на этапе [`AuthState::WaitPhoneNumber`].
+    /// После успешной отправки состояние изменится на `WaitCode`.
+    ///
+    /// # Arguments
+    ///
+    /// * `phone` - Номер телефона в международном формате (например, "+1234567890")
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(())` - Номер телефона принят, ожидайте SMS с кодом
+    /// * `Err(String)` - Ошибка (неверный формат, проблемы с сетью и т.д.)
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// auth_manager.send_phone_number("+1234567890".to_string()).await?;
+    /// ```
    pub async fn send_phone_number(&self, phone: String) -> Result<(), String> {
        functions::set_authentication_phone_number(phone, None, self.client_id)
            .await
@@ -54,7 +160,26 @@ impl AuthManager {
            .map_err(|e| format!("Ошибка отправки номера: {:?}", e))
    }

-    /// Отправить код подтверждения
+    /// Отправляет код подтверждения из SMS или Telegram.
+    ///
+    /// Используется на этапе [`AuthState::WaitCode`].
+    /// После успешной проверки состояние изменится на `Ready` или `WaitPassword`
+    /// (если включена двухфакторная аутентификация).
+    ///
+    /// # Arguments
+    ///
+    /// * `code` - Код подтверждения (обычно 5 цифр)
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(())` - Код верный
+    /// * `Err(String)` - Неверный код или истек срок действия
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// auth_manager.send_code("12345".to_string()).await?;
+    /// ```
    pub async fn send_code(&self, code: String) -> Result<(), String> {
        functions::check_authentication_code(code, self.client_id)
            .await
@@ -62,7 +187,27 @@ impl AuthManager {
            .map_err(|e| format!("Ошибка проверки кода: {:?}", e))
    }

-    /// Отправить пароль 2FA
+    /// Отправляет пароль двухфакторной аутентификации (2FA).
+    ///
+    /// Используется на этапе [`AuthState::WaitPassword`] (только если 2FA включена).
+    /// После успешной проверки состояние изменится на `Ready`.
+    ///
+    /// # Arguments
+    ///
+    /// * `password` - Пароль двухфакторной аутентификации
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(())` - Пароль верный, авторизация завершена
+    /// * `Err(String)` - Неверный пароль
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// if auth_manager.state == AuthState::WaitPassword {
+    ///     auth_manager.send_password("my_2fa_password".to_string()).await?;
+    /// }
+    /// ```
    pub async fn send_password(&self, password: String) -> Result<(), String> {
        functions::check_authentication_password(password, self.client_id)
            .await