Добавлена документация

docs/API_REFERENCE.md

@@ -0,0 +1,57 @@
+# API Reference (краткий)
+
+Документ перечисляет публичные API фреймворка и их назначение.
+
+## BotPages.Core
+
+### `BotPagesApp`
+- `AddAdapter(string messengerType, IMessangerAdapterSetup adapter)` — зарегистрировать адаптер для мессенджера.
+- `AddDefaultPage<TPage>() where TPage : SingletonPage` — установить "домашнюю" страницу приложения.
+- `AddMiddleware<TMiddleware>(TMiddleware instance) where TMiddleware : IPageMiddleware` — добавить middleware в конвейер.
+- `MapCommand<TPage>(string commandTemplate) where TPage : Page` — зарегистрировать команду, ведущую на страницу.
+- `MapCommand(string template, CommandHandler handler)` — зарегистрировать кастомный обработчик команды.
+- `MapRoute<TPage>(string template) where TPage : Page` — вручную зарегистрировать маршрут для страницы.
+- `AutoMapRoute()` — автоматически найти и зарегистрировать все Page-типы в загруженных сборках.
+- `HandleUpdateAsync(UpdateContext update, CancellationToken ct)` — главный обработчик апдейтов (вызвается адаптером).
+- `Build(CancellationToken ct)` — запустить все адаптеры и начать обработку апдейтов.
+
+### Страницы
+- `Page` — абстрактный базовый класс.
+- `StatefulPage` — страница с сохранением состояния.
+- `SingletonPage` — одноэкземплярная страница.
+
+### Навигация
+- `NavigationService` — отвечает за определение текущей страницы и переходы.
+  - `GoToAsync<TPage>(PageContext ctx, CancellationToken ct)`
+  - `GoToHomeAsync(PageContext ctx, CancellationToken ct)`
+
+### Команды
+- `CommandsRegistry` — реестр команд (внутренний). Поддерживает шаблоны с именованными аргументами и опциональными параметрами.
+
+### Middleware
+- `IPageMiddleware` — интерфейс middleware.
+  - `InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)`
+
+### Абстракции адаптеров
+- `IMessangerAdapterSetup` — настройка адаптера.
+- `IMessengerAdapter` — экземпляр адаптера, реализующий `StartAdapterAsync(Func<UpdateContext, Task> onUpdate, List<Command> commands, CancellationToken ct)`.
+- `IMessengerAdapterFactory` — фабрика/реестр адаптеров (`MultiAdapterFactory` — реализация).
+
+### Хранилище состояний
+- `IStateStorage` — абстракция для сохранения состояния страниц между сессиями.
+
+## BotPages.Telegram
+- Реализация адаптера для Telegram на базе `Telegram.Bot`.
+- `TelegramUpdateMapper` — маппит апдейты Telegram в `UpdateContext`.
+- `TelegramAlbumBuilder` — собирает медиа-альбомы из последовательных апдейтов.
+- `TelegramAdapter` — реализация адаптера, стартует `StartAdapterAsync`.
+
+
+# Генерация документации
+
+Рекомендуется использовать `docfx` или `Doxygen` для генерации HTML-документации из XML-файлов, которые генерируются при сборке (см. `GenerateDocumentationFile` в `.csproj`).
+
+
+# Примечания
+
+Этот документ — краткое описание API. Для полного списка публичных типов и методов можно сгенерировать reference из XML-вывода компиляции.