comment pass

Assets/Engine/Runtime/Measurements/PuzzleStorage.cs

@@ -7,12 +7,22 @@ using LogType = EscapeRoomEngine.Engine.Runtime.Utilities.LogType;
 
 namespace EscapeRoomEngine.Engine.Runtime.Measurements
 {
+    /// <summary>
+    /// The storage engine that manages the data in a realm database.
+    /// </summary>
     public class PuzzleStorage : MonoBehaviour
     {
+        /// <summary>
+        /// The schema version must be updated whenever the schema in the database changed.
+        /// </summary>
         private const int SchemaVersion = 2;
         
+        /// <summary>
+        /// The active instance of the storage engine.
+        /// </summary>
         public static PuzzleStorage Instance { get; private set; }
 
+        [Tooltip("The path of the database relative to where the engine stores persistent data.")]
         [SerializeField]
         private string databasePath = "measurements.realm";
         
@@ -20,6 +30,7 @@ namespace EscapeRoomEngine.Engine.Runtime.Measurements
 
         private void OnEnable()
         {
+            // configure special actions during specific migrations of the database
             var config = new RealmConfiguration
             {
                 SchemaVersion = SchemaVersion,
@@ -59,6 +70,9 @@ namespace EscapeRoomEngine.Engine.Runtime.Measurements
 
         #region Session
 
+        /// <summary>
+        /// End a session and store it to the database.
+        /// </summary>
         public void EndSession(Session session, float time)
         {
             session.Time = time;
@@ -70,6 +84,10 @@ namespace EscapeRoomEngine.Engine.Runtime.Measurements
 
         #region Puzzles
 
+        /// <summary>
+        /// Create a new puzzle for a specific description and store it in the database.
+        /// </summary>
+        /// <remarks>This requires that the puzzle does not yet exist in the database.</remarks>
         private Puzzle New(PuzzleModuleDescription puzzle)
         {
             Puzzle created = null;
@@ -79,10 +97,20 @@ namespace EscapeRoomEngine.Engine.Runtime.Measurements
             return created;
         }
 
+        /// <summary>
+        /// Load a specific puzzle from the database or create it if it wasn't found.
+        /// </summary>
         private Puzzle LoadOrNew(PuzzleModuleDescription puzzle) => _realm.Find<Puzzle>(puzzle.Id) ?? New(puzzle);
 
+        /// <summary>
+        /// Load a specific puzzle from the database.
+        /// </summary>
+        /// <returns>The puzzle or null if it wasn't found in the database.</returns>
         public Puzzle Load(PuzzleModuleDescription puzzle) => _realm.Find<Puzzle>(puzzle.Id);
         
+        /// <summary>
+        /// Delete all records concerning a specific puzzle from the database irreversibly.
+        /// </summary>
         public void Delete(PuzzleModuleDescription puzzle)
         {
             var found = Load(puzzle);
@@ -92,6 +120,9 @@ namespace EscapeRoomEngine.Engine.Runtime.Measurements
             }
         }
 
+        /// <summary>
+        /// End the measurement for a specific puzzle and store it in the database. Also stores the results of the current puzzle plan.
+        /// </summary>
         public void EndMeasurement(Session session, PuzzleModuleDescription puzzle, PuzzleMeasurement measurement)
         {
             var found = LoadOrNew(puzzle);