docs: add rustdoc comments for public API (P4.12 partial)

- Add comprehensive documentation for TdClient:
  * Struct-level docs with examples
  * Authentication methods (send_phone_number, send_code, send_password)
  * Chat methods (load_chats, load_folder_chats, leave_chat, get_profile_info)
  * All methods now have parameter docs, return types, and error descriptions

- Add comprehensive documentation for App:
  * Struct-level docs with state machine explanation
  * Constructor documentation
  * Examples for common usage patterns

- Progress: +60 doc comment lines (210 → 270)
- Update REFACTORING_ROADMAP.md (P4.12 partial completion)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

src/tdlib/client.rs

@@ -18,6 +18,31 @@ use super::reactions::ReactionManager;
 use super::types::{ChatInfo, FolderInfo, ForwardInfo, MessageInfo, NetworkState, ProfileInfo, ReactionInfo, ReplyInfo, UserOnlineStatus};
 use super::users::UserCache;
 
+/// TDLib client wrapper for Telegram integration.
+///
+/// Provides high-level API for authentication, chat management, messaging,
+/// and user caching. Delegates functionality to specialized managers:
+/// - `AuthManager` for authentication flow
+/// - `ChatManager` for chat operations
+/// - `MessageManager` for message operations
+/// - `UserCache` for user information caching
+/// - `ReactionManager` for message reactions
+///
+/// # Examples
+///
+/// ```no_run
+/// use tele_tui::tdlib::TdClient;
+///
+/// let mut client = TdClient::new();
+///
+/// // Start authorization
+/// client.send_phone_number("+1234567890".to_string()).await?;
+/// client.send_code("12345".to_string()).await?;
+///
+/// // Load chats
+/// client.load_chats(50).await?;
+/// # Ok::<(), String>(())
+/// ```
 pub struct TdClient {
     pub api_id: i32,
     pub api_hash: String,
@@ -36,6 +61,14 @@ pub struct TdClient {
 
 #[allow(dead_code)]
 impl TdClient {
+    /// Creates a new TDLib client instance.
+    ///
+    /// Reads API credentials from environment variables `API_ID` and `API_HASH`.
+    /// Initializes all managers and sets initial network state to Connecting.
+    ///
+    /// # Returns
+    ///
+    /// A new `TdClient` instance ready for authentication.
     pub fn new() -> Self {
         let api_id = env::var("API_ID")
             .unwrap_or_else(|_| "0".to_string())
@@ -58,35 +91,121 @@ impl TdClient {
     }
 
     // Делегирование к auth
+
+    /// Checks if the user is authenticated.
+    ///
+    /// # Returns
+    ///
+    /// `true` if authentication is complete, `false` otherwise.
     pub fn is_authenticated(&self) -> bool {
         self.auth.is_authenticated()
     }
 
+    /// Sends phone number for authentication.
+    ///
+    /// This is the first step of the authentication flow.
+    ///
+    /// # Arguments
+    ///
+    /// * `phone` - Phone number in international format (e.g., "+1234567890")
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the phone number is invalid or network request fails.
     pub async fn send_phone_number(&self, phone: String) -> Result<(), String> {
         self.auth.send_phone_number(phone).await
     }
 
+    /// Sends authentication code received via SMS.
+    ///
+    /// This is the second step of the authentication flow.
+    ///
+    /// # Arguments
+    ///
+    /// * `code` - Authentication code (typically 5 digits)
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the code is invalid or expired.
     pub async fn send_code(&self, code: String) -> Result<(), String> {
         self.auth.send_code(code).await
     }
 
+    /// Sends 2FA password if required.
+    ///
+    /// This is the third step of the authentication flow (if 2FA is enabled).
+    ///
+    /// # Arguments
+    ///
+    /// * `password` - Two-factor authentication password
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the password is incorrect.
     pub async fn send_password(&self, password: String) -> Result<(), String> {
         self.auth.send_password(password).await
     }
 
     // Делегирование к chat_manager
+
+    /// Loads chats from the main chat list.
+    ///
+    /// Loads up to `limit` chats from ChatList::Main, excluding archived chats.
+    /// Filters out "Deleted Account" chats automatically.
+    ///
+    /// # Arguments
+    ///
+    /// * `limit` - Maximum number of chats to load (typically 50-200)
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the network request fails.
     pub async fn load_chats(&mut self, limit: i32) -> Result<(), String> {
         self.chat_manager.load_chats(limit).await
     }
 
+    /// Loads chats from a specific folder.
+    ///
+    /// # Arguments
+    ///
+    /// * `folder_id` - Folder ID (1-9 for user folders)
+    /// * `limit` - Maximum number of chats to load
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the folder doesn't exist or network request fails.
     pub async fn load_folder_chats(&mut self, folder_id: i32, limit: i32) -> Result<(), String> {
         self.chat_manager.load_folder_chats(folder_id, limit).await
     }
 
+    /// Leaves a group or channel.
+    ///
+    /// # Arguments
+    ///
+    /// * `chat_id` - ID of the chat to leave
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the user is not a member or network request fails.
     pub async fn leave_chat(&self, chat_id: ChatId) -> Result<(), String> {
         self.chat_manager.leave_chat(chat_id).await
     }
 
+    /// Gets profile information for a chat.
+    ///
+    /// Fetches detailed information including bio, username, member count, etc.
+    ///
+    /// # Arguments
+    ///
+    /// * `chat_id` - ID of the chat
+    ///
+    /// # Returns
+    ///
+    /// `ProfileInfo` with chat details
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the chat doesn't exist or network request fails.
     pub async fn get_profile_info(&self, chat_id: ChatId) -> Result<ProfileInfo, String> {
         self.chat_manager.get_profile_info(chat_id).await
     }