add missing documentation and improve older documentation

lib/components/subject_management/subject_screen.dart

@@ -15,7 +15,7 @@ import 'package:timetable/provider/settings.dart';
 import 'package:timetable/provider/subjects.dart';
 import 'package:timetable/provider/timetables.dart';
 
-/// The Subject creation/modification screen.
+/// Subject creation/modification UI.
 class SubjectScreen extends HookConsumerWidget {
   final int? rowIndex;
   final int? columnIndex;

lib/components/widgets/views/grid_view/grid_view_overlapping_subjects_builder.dart

@@ -10,6 +10,8 @@ import 'package:timetable/provider/settings.dart';
 import 'package:timetable/components/subject_management/subject_screen.dart';
 
 /// Overlapping Subjects Builder for the grid view.
+// TODO: currently overlapping subjects need their own builder,
+// why can't I use the the regular subject builder and split the width?
 class OverlappingSubjBuilder extends ConsumerWidget {
   final List<SubjectData> subjects;
   final int earlierStartTimeHour;

lib/constants/rotation_weeks.dart

@@ -1,4 +1,4 @@
-/// Basic Rotation Weeks.
+/// Basic Rotation Weeks definition.
 enum RotationWeeks {
   all,
   none,

lib/db/database.dart

@@ -11,6 +11,18 @@ import 'package:timetable/db/models/subject.dart';
 
 part 'database.g.dart';
 
+/// manages the application's database connection and schema.
+///
+/// tables: Timetable, Subject
+/// this handles:
+/// - database initialization
+/// - schema migrations
+/// - table definitions
+/// - database provider setup
+///
+/// migration strategy:
+/// - v1 -> v2: Color storage format change
+/// - v2 -> v3: Added timetable name and subject timetable columns
 @DriftDatabase(tables: [Timetable, Subject])
 class AppDatabase extends _$AppDatabase {
   AppDatabase() : super(openConnection());

lib/db/models/subject.dart

@@ -5,6 +5,7 @@ import 'package:timetable/db/converters/color.dart';
 import 'package:timetable/db/converters/time_of_day.dart';
 import 'package:timetable/db/database.dart';
 
+/// Subject table definition and data model
 class Subject extends Table {
   IntColumn get id => integer().autoIncrement()();
   TextColumn get label => text()();

lib/db/models/timetable.dart

@@ -1,5 +1,6 @@
 import 'package:drift/drift.dart';
 
+/// Timetable table definition and data model
 class Timetable extends Table {
   IntColumn get id => integer().autoIncrement()();
   TextColumn get name => text()();

lib/db/services/service.dart

@@ -13,6 +13,7 @@ final String date =
     '${now.year}-${now.month}-${now.day}_${now.hour}-${now.minute}';
 final String fileName = 'timetable_backup $date.json';
 
+/// handles data export/backup
 void exportData(
   AppDatabase db,
   ScaffoldFeatureController<SnackBar, SnackBarClosedReason> snackBar,
@@ -35,6 +36,7 @@ void exportData(
   }
 }
 
+/// handles data import/restore
 Future<void> restoreData(
   AppDatabase db,
 ) async {

lib/helpers/route_helper.dart

@@ -1,12 +1,11 @@
 import 'package:flutter/material.dart';
 
+/// "Custom" route transitions and navigation
 class RouteHelper<T> extends MaterialPageRoute<T> {
   RouteHelper({
-    required WidgetBuilder builder,
-    RouteSettings? settings,
+    required super.builder,
+    super.settings,
   }) : super(
-          builder: builder,
-          settings: settings,
           maintainState: false,
           fullscreenDialog: false,
         );

lib/helpers/theme_helper.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:timetable/constants/theme_options.dart';
 
+/// Theme and color scheme management
 class ThemeHelper {
   static ColorScheme getColorScheme({
     required bool monetTheming,

lib/provider/language.dart

@@ -3,7 +3,7 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 import 'package:timetable/constants/languages.dart';
 
-/// Languages' [StateNotifier].
+/// Language state management
 class LanguageNotifier extends StateNotifier<Locale> {
   LanguageNotifier() : super(languages[0]) {
     loadLanguage();

lib/provider/overlapping_subjects.dart

@@ -1,7 +1,7 @@
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:timetable/db/database.dart';
 
-/// A [StateNotifier] that holds the list of overlapping subjects.
+/// Overlapping Subjects state management
 // idea: maybe i should save the list of overlapping subjects
 // instead of trying to find them everytime the app is opened
 // should help with performance, probably

lib/provider/settings.dart

@@ -5,12 +5,13 @@ import 'package:shared_preferences/shared_preferences.dart';
 import 'package:timetable/constants/timetable_views.dart';
 import 'package:timetable/db/models/settings.dart';
 
-/// Settings' [StateNotifier].
+/// App settings state management
 class SettingsNotifier extends StateNotifier<Settings> {
   SettingsNotifier() : super(Settings()) {
     loadSettings();
   }
 
+  // should be self-explanatory
   void updateDefaultSubjectDuration(Duration defaultSubjectDuration) {
     final newState = state.copyWith(
       defaultSubjectDuration: defaultSubjectDuration,

lib/provider/subjects.dart

@@ -3,7 +3,9 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:timetable/db/database.dart';
 import 'package:timetable/provider/overlapping_subjects.dart';
 
-/// Subjects' [StateNotifier]
+/// Subject state management
+/// manages CRUD operations for subjects, handles subject filtering and state updates
+/// also manages subject-timetable relationships
 class SubjectNotifier extends StateNotifier<List<SubjectData>> {
   AppDatabase db;
   OverlappingSubjects overlappingSubjectsNotifier;
@@ -23,7 +25,7 @@ class SubjectNotifier extends StateNotifier<List<SubjectData>> {
   }
 
   /// adds a subject ([SubjectCompanion]) to the database ([$SubjectTable])
-  // i use [SubjectData] in the SCS so i have to convert it everytime
+  // i use [SubjectData] in the subject creation screen so i have to convert it everytime
   Future addSubject(SubjectCompanion entry) async {
     db.subject.insertOne(
       SubjectCompanion.insert(

lib/provider/themes.dart

@@ -2,7 +2,7 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 import 'package:timetable/constants/theme_options.dart';
 
-/// Themes' [StateNotifier].
+/// Theme state management
 class ThemeNotifier extends StateNotifier<ThemeOption> {
   ThemeNotifier() : super(ThemeOption.auto) {
     loadTheme();

lib/provider/timetables.dart

@@ -3,7 +3,9 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import 'package:timetable/db/database.dart';
 import 'package:timetable/provider/subjects.dart';
 
-/// Timetables' [StateNotifier]
+/// Timetable state management
+/// multiple timetable support, manages timetable CRUD operations
+/// and default timetable handling
 class TimetableNotifier extends StateNotifier<List<TimetableData>> {
   AppDatabase db;
   SubjectNotifier subjectsNotifier;