Documentation modifications

adas-core.Infrastructure/Repositories/PumpObservationRepository.cs

@@ -23,6 +23,12 @@ namespace adas_core.Infrastructure.Repositories
 
      
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PumpObservationRepository"/> class, capturing the <see cref="ApiSettings"/> configuration and forwarding the <see cref="IMongoDatabase"/> to the base repository to back pump observation data.
+        /// </summary>
+        /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing API configuration values assigned to the repository.</param>
+        /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base class to supply the MongoDB connection.</param>
+        /// <!-- aidoc:v1 sig=8a1d3fa body=12fddac -->
         public PumpObservationRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
         {
             _apiSettings = apiSettings.Value;
@@ -37,6 +43,10 @@ namespace adas_core.Infrastructure.Repositories
                     return _apiSettings.PumpObservations ?? "pump_observations";
                 }
 
+        /// <summary>
+        /// Creates the MongoDB indexes for the <see cref="PumpObservation"/> collection, defining a compound index on <see cref="PumpObservation.DeviceId"/> (ascending) and <see cref="PumpObservation.Time"/> (descending) to optimize per-pump timeline queries and a single-field index on <see cref="PumpObservation.PatientId"/> for patient-scoped lookups. A commented TTL index on <see cref="PumpObservation.Time"/> is included as a reference for enabling direct MongoDB retention when needed.
+        /// </summary>
+        /// <!-- aidoc:v1 sig=4955da2 body=e820feb -->
         public override async Task CreateIndexes()
         {
             var indexModels = new List<CreateIndexModel<PumpObservation>>
@@ -149,6 +159,12 @@ namespace adas_core.Infrastructure.Repositories
                     return await query.ToListAsync();
                 }
         
+        /// <summary>
+        /// Asynchronously retrieves the most recent observation time for every patient that has at least one observation with a non-null patient identifier, by running a MongoDB aggregation that groups observations by patient and selects the maximum time per group.
+        /// Documents whose grouped identifier is not an <see cref="ObjectId"/> or whose maximum time is not a valid <see cref="DateTime"/> are skipped from the result, and the remaining timestamps are normalized to UTC.
+        /// </summary>
+        /// <returns>A <see cref="Task{Dictionary}"/> that yields a dictionary keyed by the patient's <see cref="ObjectId"/> with the latest observation <see cref="DateTime"/> as the value.</returns>
+        /// <!-- aidoc:v1 sig=9cf32b6 body=db998dd -->
         public async Task<Dictionary<ObjectId, DateTime>> FindAllLastPatientObservationTimeAsync()
         {
             // Pipeline:
@@ -321,6 +337,14 @@ namespace adas_core.Infrastructure.Repositories
                 }
 
 
+        /// <summary>
+        /// Deletes older <see cref="PumpObservation"/> entries for the specified <paramref name="name"/>, keeping only the <paramref name="maxCount"/> most recent records ordered by <see cref="PumpObservation.Time"/>.
+        /// Returns <c>0</c> when <paramref name="name"/> is null or whitespace, when the existing count does not exceed <paramref name="maxCount"/>, or when there is nothing left to delete after skipping the most recent items.
+        /// </summary>
+        /// <param name="name">Name used to filter the <see cref="PumpObservation"/> documents to be considered for deletion.</param>
+        /// <param name="maxCount">Maximum number of most recent <see cref="PumpObservation"/> entries to retain; any additional older entries will be removed.</param>
+        /// <returns>The number of <see cref="PumpObservation"/> documents deleted, or <c>0</c> when no deletion was required.</returns>
+        /// <!-- aidoc:v1 sig=ae5008a body=6960e61 -->
         public async Task<long> DeleteOlderNumberAsync(string name, int maxCount)
         {
             if (string.IsNullOrWhiteSpace(name))