Documentation modifications

adas-core.Infrastructure/Utils/MongoUtils.cs

@@ -9,6 +9,12 @@ namespace adas_core.Infrastructure.Utils;
 /// </summary>
 public class MongoUtils
 {
+    /// <summary>
+    /// Ensures that the indexes defined in <paramref name="expectedIndexes"/> are present on the <see cref="IMongoCollection{TDocument}"/> supplied via <paramref name="collection"/>. For each expected index, an existing index with the same key specification is left unchanged when its options match, or dropped and recreated when they differ (except for the built-in <c>_id_</c> index, which is never dropped); if no matching index exists the index is created, and MongoDB conflicts reported with code 85 are logged and tolerated.
+    /// </summary>
+    /// <param name="collection">The <see cref="IMongoCollection{TDocument}"/> whose indexes are inspected and reconciled.</param>
+    /// <param name="expectedIndexes">The set of <see cref="CreateIndexModel{TDocument}"/> definitions that the collection should contain.</param>
+    /// <!-- aidoc:v1 sig=e61054a body=29c4862 -->
     public static async Task EnsureIndexes<TDocument>(IMongoCollection<TDocument> collection,
         List<CreateIndexModel<TDocument>> expectedIndexes)
     {
@@ -74,6 +80,16 @@ public class MongoUtils
         }
     }
 
+    /// <summary>
+    /// Determines whether the options of an existing index match the expected <see cref="CreateIndexModel{TDocument}"/> options by comparing the <c>unique</c>, <c>background</c>, and <c>partialFilterExpression</c> values.
+    /// Missing boolean fields in <paramref name="existingIndex"/> are treated as <c>false</c>.
+    /// </summary>
+    /// <typeparam name="TDocument">The type of the document the index is defined on.</typeparam>
+    /// <param name="expectedIndexModel">The <see cref="CreateIndexModel{TDocument}"/> containing the expected <c>Unique</c>, <c>Background</c>, and <c>PartialFilterExpression</c> values.</param>
+    /// <param name="existingIndex">The <see cref="BsonDocument"/> representing the existing index whose options should be checked.</param>
+    /// <param name="renderArgs">The <see cref="RenderArgs{TDocument}"/> used to render the expected partial filter expression for comparison.</param>
+    /// <returns><c>true</c> if the unique flag, background flag, and rendered partial filter expression all match the expected values; otherwise <c>false</c>.</returns>
+    /// <!-- aidoc:v1 sig=04d4638 body=0088af8 -->
     private static bool IndexOptionsMatch<TDocument>(CreateIndexModel<TDocument> expectedIndexModel,
         BsonDocument existingIndex, RenderArgs<TDocument> renderArgs)
     {