From 016fb91379d9586684edd811c15e6a261a03c5d7 Mon Sep 17 00:00:00 2001 From: Username * Date: Thu, 26 Dec 2024 20:29:03 +0100 Subject: [PATCH] add missing documentation and improve older documentation --- .../subject_management/subject_screen.dart | 2 +- .../grid_view_overlapping_subjects_builder.dart | 2 ++ lib/constants/rotation_weeks.dart | 2 +- lib/db/database.dart | 12 ++++++++++++ lib/db/models/subject.dart | 1 + lib/db/models/timetable.dart | 1 + lib/db/services/service.dart | 2 ++ lib/helpers/route_helper.dart | 7 +++---- lib/helpers/theme_helper.dart | 1 + lib/provider/language.dart | 2 +- lib/provider/overlapping_subjects.dart | 2 +- lib/provider/settings.dart | 3 ++- lib/provider/subjects.dart | 6 ++++-- lib/provider/themes.dart | 2 +- lib/provider/timetables.dart | 4 +++- 15 files changed, 36 insertions(+), 13 deletions(-) diff --git a/lib/components/subject_management/subject_screen.dart b/lib/components/subject_management/subject_screen.dart index 88559a2..0ce6ffa 100644 --- a/lib/components/subject_management/subject_screen.dart +++ b/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; diff --git a/lib/components/widgets/views/grid_view/grid_view_overlapping_subjects_builder.dart b/lib/components/widgets/views/grid_view/grid_view_overlapping_subjects_builder.dart index 9fb0fb2..1cc943b 100644 --- a/lib/components/widgets/views/grid_view/grid_view_overlapping_subjects_builder.dart +++ b/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 subjects; final int earlierStartTimeHour; diff --git a/lib/constants/rotation_weeks.dart b/lib/constants/rotation_weeks.dart index 3aa40a0..9d87fd4 100644 --- a/lib/constants/rotation_weeks.dart +++ b/lib/constants/rotation_weeks.dart @@ -1,4 +1,4 @@ -/// Basic Rotation Weeks. +/// Basic Rotation Weeks definition. enum RotationWeeks { all, none, diff --git a/lib/db/database.dart b/lib/db/database.dart index 56a11db..b248ece 100644 --- a/lib/db/database.dart +++ b/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()); diff --git a/lib/db/models/subject.dart b/lib/db/models/subject.dart index 8e7ad25..e4dce58 100644 --- a/lib/db/models/subject.dart +++ b/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()(); diff --git a/lib/db/models/timetable.dart b/lib/db/models/timetable.dart index 9543409..3b0aa82 100644 --- a/lib/db/models/timetable.dart +++ b/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()(); diff --git a/lib/db/services/service.dart b/lib/db/services/service.dart index e14c4db..c024359 100644 --- a/lib/db/services/service.dart +++ b/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, @@ -35,6 +36,7 @@ void exportData( } } +/// handles data import/restore Future restoreData( AppDatabase db, ) async { diff --git a/lib/helpers/route_helper.dart b/lib/helpers/route_helper.dart index 5b143f3..4c13e5f 100644 --- a/lib/helpers/route_helper.dart +++ b/lib/helpers/route_helper.dart @@ -1,12 +1,11 @@ import 'package:flutter/material.dart'; +/// "Custom" route transitions and navigation class RouteHelper extends MaterialPageRoute { RouteHelper({ - required WidgetBuilder builder, - RouteSettings? settings, + required super.builder, + super.settings, }) : super( - builder: builder, - settings: settings, maintainState: false, fullscreenDialog: false, ); diff --git a/lib/helpers/theme_helper.dart b/lib/helpers/theme_helper.dart index 2504769..15694b9 100644 --- a/lib/helpers/theme_helper.dart +++ b/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, diff --git a/lib/provider/language.dart b/lib/provider/language.dart index b34b991..7fdfdd3 100644 --- a/lib/provider/language.dart +++ b/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 { LanguageNotifier() : super(languages[0]) { loadLanguage(); diff --git a/lib/provider/overlapping_subjects.dart b/lib/provider/overlapping_subjects.dart index 4b1594d..c1eaeeb 100644 --- a/lib/provider/overlapping_subjects.dart +++ b/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 diff --git a/lib/provider/settings.dart b/lib/provider/settings.dart index ca60e9c..d022d5a 100644 --- a/lib/provider/settings.dart +++ b/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 { SettingsNotifier() : super(Settings()) { loadSettings(); } + // should be self-explanatory void updateDefaultSubjectDuration(Duration defaultSubjectDuration) { final newState = state.copyWith( defaultSubjectDuration: defaultSubjectDuration, diff --git a/lib/provider/subjects.dart b/lib/provider/subjects.dart index a99c7a1..77d10c2 100644 --- a/lib/provider/subjects.dart +++ b/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> { AppDatabase db; OverlappingSubjects overlappingSubjectsNotifier; @@ -23,7 +25,7 @@ class SubjectNotifier extends StateNotifier> { } /// 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( diff --git a/lib/provider/themes.dart b/lib/provider/themes.dart index 626711f..799a834 100644 --- a/lib/provider/themes.dart +++ b/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 { ThemeNotifier() : super(ThemeOption.auto) { loadTheme(); diff --git a/lib/provider/timetables.dart b/lib/provider/timetables.dart index 70fd054..027ab21 100644 --- a/lib/provider/timetables.dart +++ b/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> { AppDatabase db; SubjectNotifier subjectsNotifier;