Feature/docs

lib/objectbox.dart

@@ -4,23 +4,36 @@ import 'package:path_provider/path_provider.dart';
 import 'objectbox.g.dart';
 import 'src/services/entry.dart'; // created by `flutter pub run build_runner build`
 
+/// This class represents a Objectbox store instance used throughout the application.
 class D2ObjectBox {
-  /// The Store of this app.
+  /// The underlying store instance.
   final Store store;
+
+  /// Identifier for the store instance.
   final String storeId;
 
+  /// Private constructor for creating a [D2ObjectBox] instance.
+  ///
+  /// Use [createTest] or [create] static methods to instantiate [D2ObjectBox].
   D2ObjectBox._create(this.store, this.storeId) {
     // Add any additional setup code, e.g. build queries.
   }
 
+  /// Creates a test instance of [D2ObjectBox] with an in-memory store.
+  ///
+  /// Returns a [Future] that completes with the created [D2ObjectBox] instance.
   static Future<D2ObjectBox> createTest() async {
     final store = await openStore(
       directory: "memory:test-db",
     );
     return D2ObjectBox._create(store, "test");
   }
 
-  /// Create an instance of ObjectBox to use throughout the app.
+  /// Creates an instance of [D2ObjectBox] for use throughout the application.
+  ///
+  /// - Takes [credentials] of type [D2UserCredential] to identify the store.
+  ///
+  /// Returns a [Future] that completes with the created [D2ObjectBox] instance.
   static Future<D2ObjectBox> create(D2UserCredential credentials) async {
     String storeId = credentials.id;
     final docsDir = await getApplicationDocumentsDirectory();

lib/src/models/data/base.dart

@@ -1,15 +1,24 @@
 import 'upload_base.dart';
 
+/// This is class represents a data resource in the DHIS2 system.
 abstract class D2DataResource {
+  /// The ID of the data resource.
   abstract int id;
+
+  /// The date and time when the data resource was created.
   abstract DateTime createdAt;
+
+  /// The date and time when the data resource was last updated.
   abstract DateTime updatedAt;
 
+  /// Creates a [D2DataResource] instance from a map.
   static D2DataResource? fromMap() {
     return null;
   }
 }
 
+/// This class represents a synchronized data source.
 abstract class SyncDataSource extends D2DataResource implements SyncableData {
+  /// The unique identifier (UID) of the sync data source.
   abstract String uid;
 }

lib/src/models/data/data_store.dart

@@ -6,8 +6,11 @@ import '../../../objectbox.dart';
 import '../../repositories/data/data_store.dart';
 
 @Entity()
+
+/// This class represents a data store in the DHIS2 system.
 class D2DataStore {
   int id = 0;
+
   @Index()
   String key;
 
@@ -19,15 +22,30 @@ class D2DataStore {
 
   String value;
 
+  /// Constructs a new instance of [D2DataStore].
+  ///
+  /// - [key] The key associated with the data store.
+  /// - [namespace] The namespace of the data store.
+  /// - [value] The value stored as a JSON encoded string.
+  /// - [uid] The unique identifier for the data store.
   D2DataStore(this.key, this.namespace, this.value, this.uid);
 
+  /// Constructs a new instance of [D2DataStore] from a map.
+  ///
+  /// - [db] The database reference for fetching related entities.
+  /// - [namespace] The namespace of the data store.
+  /// - [key] The key associated with the data store.
+  /// - [value] The value to be stored, which will be JSON encoded.
   D2DataStore.fromMap(D2ObjectBox db,
       {required this.namespace, required this.key, required Object value})
       : value = jsonEncode(value),
         uid = "$namespace-$key" {
     id = D2DataStoreRepository(db).getIdByUid(uid) ?? 0;
   }
 
+  /// Retrieves the value stored in the data store.
+  ///
+  /// - Returns the decoded value.
   getValue<T>() {
     return jsonDecode(value) as T;
   }

lib/src/models/data/data_value.dart

@@ -11,6 +11,8 @@ import 'event.dart';
 import 'upload_base.dart';
 
 @Entity()
+
+/// This class represents a data value in the DHIS2 system.
 class D2DataValue extends D2DataResource
     implements SyncableData, D2BaseEditable {
   @override
@@ -30,9 +32,23 @@ class D2DataValue extends D2DataResource
 
   final dataElement = ToOne<D2DataElement>();
 
+  /// Constructs a new instance of [D2DataValue].
+  ///
+  /// - [uid] The unique identifier for the data value.
+  /// - [id] The ID of the data value.
+  /// - [createdAt] The creation timestamp of the data value.
+  /// - [updatedAt] The last updated timestamp of the data value.
+  /// - [value] The value stored.
+  /// - [providedElsewhere] Whether the value is provided elsewhere.
+  /// - [synced] Whether the value is synced.
   D2DataValue(this.uid, this.id, this.createdAt, this.updatedAt, this.value,
       this.providedElsewhere, this.synced);
 
+  /// Constructs a new instance of [D2DataValue] from a map.
+  ///
+  /// - [db] The database reference for fetching related entities.
+  /// - [json] The JSON map containing data value information.
+  /// - [eventId] The event ID related to the data value.
   D2DataValue.fromMap(D2ObjectBox db, Map json, String eventId)
       : updatedAt = DateTime.parse(json["updatedAt"]),
         createdAt = DateTime.parse(json["createdAt"]),
@@ -47,6 +63,11 @@ class D2DataValue extends D2DataResource
         D2DataElementRepository(db).getByUid(json["dataElement"]);
   }
 
+  /// Constructs a new instance of [D2DataValue] from form values.
+  ///
+  /// - [value] The value to be stored.
+  /// - [event] The related event.
+  /// - [dataElement] The related data element.
   D2DataValue.fromFormValues(this.value,
       {required D2Event event, required D2DataElement dataElement})
       : updatedAt = DateTime.now(),
@@ -60,6 +81,9 @@ class D2DataValue extends D2DataResource
   @override
   bool synced = true;
 
+  /// Retrieves the display value of the data element.
+  ///
+  /// Returns the display value as [String].
   String? getDisplayValue() {
     if (dataElement.target!.optionSet.target == null) {
       return value;
@@ -70,16 +94,30 @@ class D2DataValue extends D2DataResource
     return valueOption?.displayName ?? valueOption?.name ?? value;
   }
 
+  /// Converts the data value to a map.
+  ///
+  /// - [db] The database reference, optional.
+  ///
+  /// Returns a [Future] containing the map of data value information.
   @override
   Future<Map<String, dynamic>> toMap({D2ObjectBox? db}) async {
     return {"dataElement": dataElement.target?.uid, "value": value};
   }
 
+  /// Converts the data value to form values.
+  ///
+  /// Returns a map of form values.
   @override
   Map<String, dynamic> toFormValues() {
     return {dataElement.target!.uid: value};
   }
 
+  /// Updates the data value from form values.
+  ///
+  /// - [values] The map of form values.
+  /// - [db] The database reference.
+  /// - [program] The related program, optional.
+  /// - [orgUnit] The related organisation unit, optional.
   @override
   void updateFromFormValues(Map<String, dynamic> values,
       {required D2ObjectBox db, D2Program? program, D2OrgUnit? orgUnit}) {
@@ -90,6 +128,9 @@ class D2DataValue extends D2DataResource
     }
   }
 
+  /// Saves the data value to the database.
+  ///
+  /// - [db] The database reference.
   @override
   void save(D2ObjectBox db) {
     D2DataValueRepository(db).saveEntity(this);

lib/src/models/data/data_value_set.dart

@@ -5,6 +5,8 @@ import 'base.dart';
 import 'base_deletable.dart';
 
 @Entity()
+
+/// This class represents a data value set in the DHIS2 system.
 class D2DataValueSet extends SyncDataSource implements D2BaseDeletable {
   @override
   int id = 0;
@@ -16,15 +18,13 @@ class D2DataValueSet extends SyncDataSource implements D2BaseDeletable {
   bool synced = true;
 
   ///For this to be unique, it has to include orgUnit, period, attributeOptionCombo, dataElement, and categoryOptionCombo. So it is generated with the format as listed separated by -
+
   @Unique()
   late String uid;
 
   String value;
-
   String period;
-
   String? comment;
-
   bool followup;
 
   D2DataValueSet(this.uid, this.id, this.createdAt, this.updatedAt, this.value,
@@ -35,6 +35,10 @@ class D2DataValueSet extends SyncDataSource implements D2BaseDeletable {
   final attributeOptionCombo = ToOne<D2CategoryOptionCombo>();
   final organisationUnit = ToOne<D2OrgUnit>();
 
+  /// Creates an instance of [D2DataValueSet] from a JSON map.
+  ///
+  /// - [db] The database reference.
+  /// - [json] The JSON map containing the data value set information.
   D2DataValueSet.fromMap(D2ObjectBox db, Map json)
       : updatedAt = DateTime.parse(json["lastUpdated"]),
         createdAt = DateTime.parse(json["created"]),
@@ -56,6 +60,15 @@ class D2DataValueSet extends SyncDataSource implements D2BaseDeletable {
     id = D2DataValueSetRepository(db).getIdByUid(uid) ?? 0;
   }
 
+  /// Creates an instance of [D2DataValueSet] from form values.
+  ///
+  /// - [db] The database reference.
+  /// - [orgUnit] The organization unit.
+  /// - [attributeOptionCombo] The attribute option combo.
+  /// - [period] The period.
+  /// - [value] The value.
+  /// - [dataElement] The data element.
+  /// - [categoryOptionCombo] The category option combo.
   D2DataValueSet.fromForm(
       {required D2ObjectBox db,
       required D2OrgUnit orgUnit,
@@ -77,6 +90,11 @@ class D2DataValueSet extends SyncDataSource implements D2BaseDeletable {
     synced = false;
   }
 
+  /// Converts the data value set to a JSON map.
+  ///
+  /// - [db] Optional database reference.
+  ///
+  /// Returns a [Future<Map<String, dynamic>>] containing the JSON map.
   @override
   Future<Map<String, dynamic>> toMap({D2ObjectBox? db}) async {
     return {
@@ -90,25 +108,38 @@ class D2DataValueSet extends SyncDataSource implements D2BaseDeletable {
     };
   }
 
+  /// Converts the data value set to form values.
+  ///
+  /// Returns a [Map] containing the form values.
   Map<String, dynamic> toFormValues() {
     if (categoryOptionCombo.target != null) {
       return {
         '${dataElement.target!.uid}.${categoryOptionCombo.target!.uid}': value
       };
     }
-
     return {dataElement.target!.uid: value};
   }
 
+  /// Saves the data value set to the database.
+  ///
+  /// - [db] The database reference.
   void save(D2ObjectBox db) {
     db.store.box<D2DataValueSet>().put(this);
   }
 
+  /// Deletes the data value set from the database.
+  ///
+  /// - [db] The database reference.
+  ///
+  /// Returns a [bool] indicating the success of the operation.
   @override
   bool delete(D2ObjectBox db) {
     return D2DataValueSetRepository(db).box.remove(id);
   }
 
+  /// Soft deletes the data value set.
+  ///
+  /// - [db] The database reference.
   @override
   void softDelete(db) {}
 }