refactor(app): Обновить описание и структуру файлов конфигурации, улучшить документацию (#14)

Co-authored-by: PetrovY <y.petrov@friflex.com>
2026-02-05 03:32:18 +00:00 · 2025-06-20 16:50:48 +03:00
parent 427a821e5d
commit ba5fdba9be
26 changed files with 476 additions and 189 deletions
--- a/lib/features/auth/presentation/screens/auth_screen.dart
+++ b/lib/features/auth/presentation/screens/auth_screen.dart
@@ -1,10 +1,17 @@
 import 'package:flutter/material.dart';

-/// {@template AuthScreen}
+/// {@template auth_screen}
+/// Экран авторизации пользователя.
 ///
+/// Отвечает за:
+/// - Отображение формы входа в приложение
+/// - Обработку процесса аутентификации
+/// - Навигацию после успешной авторизации
+///
+/// В текущей реализации является заглушкой для будущей функциональности.
 /// {@endtemplate}
 class AuthScreen extends StatelessWidget {
-  /// {@macro AuthScreen}
+  /// {@macro auth_screen}
  const AuthScreen({super.key});

  @override
--- a/lib/features/debug/screens/components_screen.dart
+++ b/lib/features/debug/screens/components_screen.dart
@@ -2,18 +2,33 @@ import 'package:flutter/material.dart';
 import 'package:friflex_starter/app/ui_kit/app_box.dart';
 import 'package:friflex_starter/app/ui_kit/app_snackbar.dart';

-/// {@template ComponentsScreen}
-/// Экран для демонстрации компонентов приложения.
+/// {@template components_screen}
+/// Экран для демонстрации и тестирования компонентов приложения.
+///
+/// Отвечает за:
+/// - Демонстрацию различных типов снекбаров (ошибка, успех, информация)
+/// - Тестирование кастомных UI компонентов
+/// - Предоставление примеров использования компонентов
+/// - Валидацию корректности работы компонентов
 /// {@endtemplate}
 class ComponentsScreen extends StatefulWidget {
-  /// {@macro ComponentsScreen}
+  /// {@macro components_screen}
  const ComponentsScreen({super.key});

  @override
  State<ComponentsScreen> createState() => _ComponentsScreenState();
 }

+/// {@template components_screen_state}
+/// Состояние экрана компонентов.
+///
+/// Управляет отображением различных типов снекбаров
+/// и демонстрирует их функциональность.
+/// {@endtemplate}
 class _ComponentsScreenState extends State<ComponentsScreen> {
+  /// {@macro components_screen_state}
+  _ComponentsScreenState();
+
  @override
  Widget build(BuildContext context) {
    return Scaffold(
--- a/lib/features/debug/screens/icons_screen.dart
+++ b/lib/features/debug/screens/icons_screen.dart
@@ -2,11 +2,16 @@ import 'package:flutter/material.dart';
 import 'package:friflex_starter/app/ui_kit/app_box.dart';
 import 'package:friflex_starter/gen/assets.gen.dart';

-/// {@template IconsScreen}
-///  Экран для отрисовки иконок
+/// {@template icons_screen}
+/// Экран для отображения всех доступных иконок приложения.
+///
+/// Отвечает за:
+/// - Отображение списка всех SVG иконок из assets/icons/
+/// - Предоставление возможности просмотра иконок для разработчиков
+/// - Демонстрацию использования системы генерации ресурсов
 /// {@endtemplate}
 class IconsScreen extends StatelessWidget {
-  /// {@macro IconsScreen}
+  /// {@macro icons_screen}
  const IconsScreen({super.key});

  @override
@@ -30,19 +35,20 @@ class IconsScreen extends StatelessWidget {
  }
 }

-// Приватный класс для реализации элемента списка иконок
+/// {@template item_icon}
+/// Виджет для отображения отдельной иконки в списке.
+///
+/// Отображает SVG иконку вместе с её названием файла
+/// для удобства идентификации в процессе разработки.
+/// {@endtemplate}
 class _ItemIcon extends StatelessWidget {
-  /// Создает экземпляр элемента списка иконок
-  ///
-  /// Принимает:
-  /// - [icon] - иконка
-  /// - [name] - название иконки
+  /// {@macro item_icon}
  const _ItemIcon({required this.icon, required this.name});

-  /// Иконка
+  /// SVG иконка для отображения
  final Widget icon;

-  /// Название иконки
+  /// Название файла иконки для идентификации
  final String name;

  @override
--- a/lib/features/debug/screens/lang_screen.dart
+++ b/lib/features/debug/screens/lang_screen.dart
@@ -4,11 +4,17 @@ import 'package:friflex_starter/app/theme/app_colors_scheme.dart';
 import 'package:friflex_starter/gen/assets.gen.dart';
 import 'package:friflex_starter/gen/fonts.gen.dart';

-/// {@template LangScreen}
-/// Экран для отладки языков приложения
+/// {@template lang_screen}
+/// Экран для отладки и тестирования локализации приложения.
+///
+/// Отвечает за:
+/// - Демонстрацию переключения между поддерживаемыми языками
+/// - Отображение локализованных строк с разными шрифтами
+/// - Тестирование системы локализации и шрифтов
+/// - Показ текущего языка приложения
 /// {@endtemplate}
 class LangScreen extends StatelessWidget {
-  /// {@macro LangScreen}
+  /// {@macro lang_screen}
  const LangScreen({super.key});

  @override
--- a/lib/features/debug/screens/theme_screen.dart
+++ b/lib/features/debug/screens/theme_screen.dart
@@ -2,11 +2,17 @@ import 'package:flutter/material.dart';
 import 'package:friflex_starter/app/app_context_ext.dart';
 import 'package:friflex_starter/app/theme/app_colors_scheme.dart';

-/// {@template ThemeScreen}
-///  Экран для отладки темы приложения
+/// {@template theme_screen}
+/// Экран для отладки и тестирования темы приложения.
+///
+/// Отвечает за:
+/// - Демонстрацию переключения между светлой и темной темами
+/// - Отображение тестовых цветов из цветовой схемы
+/// - Показ текущего режима темы
+/// - Тестирование системы управления темами
 /// {@endtemplate}
 class ThemeScreen extends StatelessWidget {
-  /// {@macro ThemeScreen}
+  /// {@macro theme_screen}
  const ThemeScreen({super.key});

  @override
--- a/lib/features/debug/screens/tokens_screen.dart
+++ b/lib/features/debug/screens/tokens_screen.dart
@@ -1,10 +1,17 @@
 import 'package:flutter/material.dart';

-/// {@template TokensScreen}
-///  Экран для отображения токенов
+/// {@template tokens_screen}
+/// Экран для отображения и управления токенами аутентификации.
+///
+/// Отвечает за:
+/// - Отображение текущих токенов доступа и обновления
+/// - Демонстрацию работы с токенами в приложении
+/// - Тестирование функциональности аутентификации
+///
+/// В текущей реализации является заглушкой для будущей функциональности.
 /// {@endtemplate}
 class TokensScreen extends StatelessWidget {
-  /// {@macro TokensScreen}
+  /// {@macro tokens_screen}
  const TokensScreen({super.key});

  @override
--- a/lib/features/debug/screens/ui_kit_screen.dart
+++ b/lib/features/debug/screens/ui_kit_screen.dart
@@ -1,11 +1,18 @@
 import 'package:flutter/material.dart';

-/// {@template UiKitScreen}
-///  Экран для отрисовки UI Kit
-///  и тестирования его компонентов.
+/// {@template ui_kit_screen}
+/// Экран для демонстрации и тестирования компонентов UI Kit.
+///
+/// Отвечает за:
+/// - Отображение всех доступных компонентов UI Kit
+/// - Демонстрацию использования кастомных виджетов
+/// - Тестирование стилей и тем оформления
+/// - Предоставление примера использования UI компонентов
+///
+/// В текущей реализации является заглушкой для будущих компонентов.
 /// {@endtemplate}
 class UiKitScreen extends StatelessWidget {
-  /// {@macro UiKitScreen}
+  /// {@macro ui_kit_screen}
  const UiKitScreen({super.key});

  @override
--- a/lib/features/profile/domain/bloc/profile_bloc.dart
+++ b/lib/features/profile/domain/bloc/profile_bloc.dart
@@ -5,10 +5,16 @@ import 'package:friflex_starter/features/profile/domain/repository/i_profile_rep
 part 'profile_event.dart';
 part 'profile_state.dart';

+/// {@template profile_bloc}
+/// Bloc для управления состоянием профиля пользователя.
+///
+/// Обрабатывает события загрузки данных профиля и управляет
+/// соответствующими состояниями (загрузка, успех, ошибка).
+/// {@endtemplate}
 class ProfileBloc extends Bloc<ProfileEvent, ProfileState> {
+  /// {@macro profile_bloc}
  ProfileBloc(this._profileRepository) : super(ProfileInitialState()) {
-    // Вам необходимо добавлять только
-    // один обработчик событий в конструкторе
+    // Регистрируем обработчики событий в конструкторе
    on<ProfileEvent>((event, emit) async {
      if (event is ProfileFetchProfileEvent) {
        await _fetchProfile(event, emit);
@@ -16,8 +22,19 @@ class ProfileBloc extends Bloc<ProfileEvent, ProfileState> {
    });
  }

+  /// Репозиторий для работы с данными профиля
  final IProfileRepository _profileRepository;

+  /// Метод для загрузки данных профиля пользователя.
+  ///
+  /// Принимает:
+  /// - [event] - событие с ID пользователя для загрузки
+  /// - [emit] - функция для эмиссии состояний
+  ///
+  /// Последовательность состояний:
+  /// 1. ProfileWaitingState - начало загрузки
+  /// 2. ProfileSuccessState - успешная загрузка с данными
+  /// 3. ProfileErrorState - ошибка загрузки с сообщением
  Future<void> _fetchProfile(
    ProfileFetchProfileEvent event,
    Emitter<ProfileState> emit,
--- a/lib/features/profile/presentation/screens/profile_screen.dart
+++ b/lib/features/profile/presentation/screens/profile_screen.dart
@@ -3,17 +3,22 @@ import 'package:flutter_bloc/flutter_bloc.dart';
 import 'package:friflex_starter/app/app_context_ext.dart';
 import 'package:friflex_starter/features/profile/domain/bloc/profile_bloc.dart';

-// Класс экрана, где мы инициализируем ProfileBloc
-// и вызываем событие ProfileFetchProfileEvent
+/// {@template profile_screen}
+/// Экран профиля пользователя.
+///
+/// Отвечает за:
+/// - Инициализацию ProfileBloc с репозиторием профиля
+/// - Отображение данных профиля пользователя
+/// - Обработку состояний загрузки, успеха и ошибок
+/// {@endtemplate}
 class ProfileScreen extends StatelessWidget {
+  /// {@macro profile_screen}
  const ProfileScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final profileRepository = context.di.repositories.profileRepository;
-    // Здесь мы инициализируем ProfileBloc
-    // и вызываем событие ProfileFetchProfileEvent
-    // Или любые другие события, которые вам нужны
+    // Инициализируем ProfileBloc с репозиторием и загружаем данные профиля
    return BlocProvider(
      create: (context) =>
          ProfileBloc(profileRepository)
@@ -23,8 +28,16 @@ class ProfileScreen extends StatelessWidget {
  }
 }

-/// Виджет, который отображает UI экрана
+/// {@template profile_screen_view}
+/// Виджет для отображения UI экрана профиля.
+///
+/// Отображает данные профиля в зависимости от состояния ProfileBloc:
+/// - Индикатор загрузки во время получения данных
+/// - Данные профиля при успешной загрузке
+/// - Сообщение об ошибке при неудачной загрузке
+/// {@endtemplate}
 class _ProfileScreenView extends StatelessWidget {
+  /// {@macro profile_screen_view}
  const _ProfileScreenView();

  @override
--- a/lib/features/root/root_screen.dart
+++ b/lib/features/root/root_screen.dart
@@ -4,15 +4,21 @@ import 'package:friflex_starter/app/app_env.dart';
 import 'package:friflex_starter/features/debug/debug_routes.dart';
 import 'package:go_router/go_router.dart';

-/// Класс для реализации корневой страницы приложения
+/// {@template root_screen}
+/// Корневой экран приложения с навигационной структурой.
+///
+/// Отвечает за:
+/// - Отображение основного навигационного интерфейса
+/// - Управление переключением между основными разделами приложения
+/// - Отображение кнопки отладки в не-продакшн окружениях
+/// - Интеграцию с GoRouter для навигации
+/// {@endtemplate}
 class RootScreen extends StatelessWidget {
-  /// Создает корневую страницу приложения
-  ///
-  /// Принимает:
-  /// - [navigationShell] - текущая ветка навигации
+  /// {@macro root_screen}
  const RootScreen({required this.navigationShell, super.key});

-  /// Текущая ветка навигации
+  /// Текущая ветка навигации от GoRouter
+  /// Содержит информацию о текущем состоянии навигации
  final StatefulNavigationShell navigationShell;

  @override
@@ -29,7 +35,7 @@ class RootScreen extends StatelessWidget {
      body: navigationShell,
      bottomNavigationBar: BottomNavigationBar(
        items: const <BottomNavigationBarItem>[
-          BottomNavigationBarItem(icon: Icon(Icons.home), label: 'Home'),
+          BottomNavigationBarItem(icon: Icon(Icons.home), label: 'Главная'),
          BottomNavigationBarItem(icon: Icon(Icons.person), label: 'Профиль'),
        ],
        currentIndex: navigationShell.currentIndex,