fix: continuing error managment and documentation

lib/ui/bal_page/view_model/bal_view_model.dart

@@ -14,7 +14,7 @@ import 'package:seshat/utils/result.dart';
 class BalViewModel extends ChangeNotifier {
   BalViewModel({
     required BalRepository balRepository,
-    required this.id,
+    required this.selectedBalId,
     required OwnerRepository ownerRepository,
   }) : _balRepository = balRepository,
        _ownerRepository = ownerRepository {
@@ -30,18 +30,26 @@ class BalViewModel extends ChangeNotifier {
  * =====================
 */
 
-  Bal? _bal;
-  int id;
-  Bal? get bal => _bal;
+  /// Selected [Bal]
+  Bal? _selectedBal;
+
+  /// Selected [Bal]
+  Bal? get selectedBal => _selectedBal;
+
+  /// Selected [Bal.id] from path parameters
+  int selectedBalId;
+
+  /// Is one of the [Bal] [BalState.ongoing]
   bool isABalOngoing = false;
 
-  Future<Result<void>> stopBal(int id) async {
+  /// Stops a [Bal]
+  Future<Result<void>> stopBal(int balId) async {
     isLoaded = false;
     notifyListeners();
-    final result = await _balRepository.stopBal(id);
+    final result = await _balRepository.stopBal(balId);
     switch (result) {
       case Ok():
-        _bal = result.value;
+        _selectedBal = result.value;
         break;
       default:
     }
@@ -57,14 +65,15 @@ class BalViewModel extends ChangeNotifier {
     return result;
   }
 
-  Future<Result<void>> startBal(int id) async {
+  /// Starts a [Bal]
+  Future<Result<void>> startBal(int balId) async {
     if (isABalOngoing) {
       return Result.error(Exception("Cannot have multiple BALs ongoing !"));
     }
-    final result = await _balRepository.startBal(id);
+    final result = await _balRepository.startBal(balId);
     switch (result) {
       case Ok():
-        _bal = result.value;
+        _selectedBal = result.value;
         notifyListeners();
         break;
       default:
@@ -72,21 +81,20 @@ class BalViewModel extends ChangeNotifier {
     return result;
   }
 
+  /// Edits a [Bal]'s [name], [startTime] or [endTime]
   Future<Result<void>> editBal(
     int id,
     String name,
-    DateTime start,
-    DateTime end,
+    DateTime startTime,
+    DateTime endTime,
   ) async {
-    final result = await _balRepository.editBal(id, name, start, end);
+    final result = await _balRepository.editBal(id, name, startTime, endTime);
     switch (result) {
       case Ok():
-        debugPrint("\n\n\n\nDID EDIT\n\n\n\n");
-        _bal = result.value;
+        _selectedBal = result.value;
         notifyListeners();
         break;
       case Error():
-        debugPrint("\n\n\n\nERROR: ${result.error}");
         break;
     }
     return result;
@@ -99,11 +107,16 @@ class BalViewModel extends ChangeNotifier {
 */
 
   // Specific to ended state
+
+  /// Owners a book or money is owed to
   List<ReturnOwner>? owedToOwners;
-  double? totalOwed;
+
+  /// Statistics about the [_selectedBal]
   BalStats? stats;
 
-  Future<void> applyAccountingOwners(
+  /// Froms [books], updates [owners] to include all the necessary information
+  /// See [the api doc](https://bal.ueauvergne.fr/docs/#/bal-api/get_bal_accounting) for more details
+  Future<void> _updateOwedToOwnersWithBooks(
     List<ReturnOwner> owners,
     Map<String, Book> books,
   ) async {
@@ -124,15 +137,20 @@ class BalViewModel extends ChangeNotifier {
     }
   }
 
+  /// Returns either Books, Money or All ([ReturnType]) to an [Owner]
   Future<Result<void>> returnById(ReturnType type, int ownerId) async {
-    final result = await _balRepository.returnToId(id, ownerId, type);
-    final result2 = await _balRepository.getAccounting(id);
+    final result = await _balRepository.returnToId(
+      selectedBalId,
+      ownerId,
+      type,
+    );
+    final result2 = await _balRepository.getAccounting(selectedBalId);
     switch (result2) {
       case Ok():
-        applyAccountingOwners(result2.value.owners, result2.value.books);
+        _updateOwedToOwnersWithBooks(result2.value.owners, result2.value.books);
         break;
       case Error():
-        debugPrint(result2.error.toString());
+        break;
     }
     notifyListeners();
     return result;
@@ -144,22 +162,25 @@ class BalViewModel extends ChangeNotifier {
  * =================================
 */
 
+  /// Loads all the necessary information
   late final Command0 load;
   bool isLoaded = false;
 
+  /// Manages loaders
   Future<Result<void>> _load() async {
     isABalOngoing = _balRepository.isABalOngoing();
     final result1 = await _loadBal();
     switch (result1) {
       case Ok():
-        isLoaded = (_bal == null || _bal?.state != BalState.ended)
+        isLoaded =
+            (_selectedBal == null || _selectedBal?.state != BalState.ended)
             ? true
             : false;
         break;
       default:
         break;
     }
-    if (_bal?.state == BalState.ended) {
+    if (_selectedBal?.state == BalState.ended) {
       final result2 = await _loadEnded();
       switch (result2) {
         case Ok():
@@ -173,11 +194,12 @@ class BalViewModel extends ChangeNotifier {
     return result1;
   }
 
+  /// Loads all common [Bal] information
   Future<Result<void>> _loadBal() async {
-    final result = await _balRepository.balById(id);
+    final result = await _balRepository.balById(selectedBalId);
     switch (result) {
       case Ok():
-        _bal = result.value;
+        _selectedBal = result.value;
         break;
       case Error():
         break;
@@ -186,15 +208,16 @@ class BalViewModel extends ChangeNotifier {
     return result;
   }
 
+  /// Loads [Bal] information when it is [BalState.ended]
   Future<Result<void>> _loadEnded() async {
-    final result = await _balRepository.getAccountingNoCache(id);
+    final result = await _balRepository.getAccountingNoCache(selectedBalId);
     switch (result) {
       case Ok():
-        applyAccountingOwners(result.value.owners, result.value.books);
+        _updateOwedToOwnersWithBooks(result.value.owners, result.value.books);
         break;
       default:
     }
-    final result2 = await _balRepository.getBalStats(id);
+    final result2 = await _balRepository.getBalStats(selectedBalId);
     switch (result2) {
       case Ok():
         stats = result2.value;