docs(iec62304): [REL-1.0.2] apply curated XML doc review updates

adas-core.Infrastructure/Repositories/MasterListRepository.cs

@@ -113,9 +113,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Replaces the document in the collection matching the entity's identifier, or inserts it when no match exists (upsert behavior). Failures are logged and rethrown to the caller.
+    /// Persists the supplied <typeparamref name="T"/> entity in the collection by replacing the document identified by <see cref="T.Id"/>, or inserting a new document when no match is found (upsert). Logs and rethrows any exception raised during the operation.
     /// </summary>
-    /// <param name="entity">The entity to upsert; its identifier is used as the filter and <paramref name="entity"/>'s current state replaces the matched document.</param>
+    /// <typeparam name="T">The document type stored in the collection.</typeparam>
+    /// <param name="entity">The entity whose <see cref="T.Id"/> locates the target document and whose state is written to the collection.</param>
     /// <!-- aidoc:v1 sig=019b691 body=863650a -->
     public async Task Update(T entity)
     {
@@ -166,10 +167,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Asynchronously retrieves an entity of type <c>T</c> matching the specified <paramref name="id"/>, projecting the "options" array to at most 100 elements. Returns <c>null</c> when no matching document is found or when an exception is caught, with the error logged.
+    /// Asynchronously retrieves an entity of type <typeparamref name="T"/> from the collection by its <see cref="ObjectId"/>, applying a projection that truncates the <c>options</c> field to 100 elements. Returns <see langword="null"/> when no matching document is found, or when an exception is caught and logged by <see cref="Log"/>.
     /// </summary>
-    /// <param name="id">The <see cref="ObjectId"/> identifier of the entity to locate.</param>
+    /// <typeparam name="T">The document type stored in the collection, expected to expose an <see cref="ObjectId"/> identifier.</typeparam>
-    /// <returns>A <see cref="Task{T}"/> that yields the matching entity, or <c>null</c> when the entity is not found or an error occurs.</returns>
+    /// <param name="id">The <see cref="ObjectId"/> of the entity to locate.</param>
+    /// <returns>A <see cref="Task{T}"/> that resolves to the matching entity, or <see langword="null"/> if the document is not found or the operation fails.</returns>
     /// <!-- aidoc:v1 sig=81ac96a body=1519944 -->
     public async Task<T?> FindById(ObjectId id)
     {
@@ -194,14 +196,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Finds a specific option item within a master document using MongoDB aggregation, returning the localized <see cref="OptionList"/> or <c>null</c> if not found.
+    /// Retrieves a single <see cref="OptionList"/> item from a master document identified by <paramref name="masterId"/> and <paramref name="optionId"/>, applying locale-aware name resolution. When <paramref name="locale"/> is <see cref="LocaleEnum.Default"/> or matches the document's default locale, the base name is returned; otherwise, the matching entry from the <c>localeItems</c> map is used, falling back to the base name when no translation is found. Returns <see langword="null"/> when the option is not found or if an error occurs during aggregation.
-    /// Uses the provided <paramref name="locale"/> to resolve translations: when the locale is <see cref="LocaleEnum.Default"/> or matches the document's default locale, the option's main name is returned; otherwise, the matching entry in the option's <c>localeItems</c> is used, falling back to the main name when no translation exists.
-    /// Any exception raised during the aggregation or deserialization is logged and surfaced as a <c>null</c> result.
     /// </summary>
-    /// <param name="masterId">The <see cref="ObjectId"/> of the master document that contains the options array.</param>
+    /// <param name="masterId">The <see cref="ObjectId"/> of the master document that contains the option collection to search.</param>
-    /// <param name="optionId">The <see cref="ObjectId"/> of the specific option to retrieve.</param>
+    /// <param name="optionId">The <see cref="ObjectId"/> of the specific option within the master document's options array.</param>
-    /// <param name="locale">The <see cref="LocaleEnum"/> value used to select the appropriate translation.</param>
+    /// <param name="locale">The <see cref="LocaleEnum"/> value that drives translation selection; <see cref="LocaleEnum.Default"/> resolves to the document's default locale, while any other value attempts a locale-specific lookup.</param>
-    /// <returns>A <see cref="Task{OptionList}"/> that resolves to the matching <see cref="OptionList"/>, or <c>null</c> when the option is not found or an error occurs.</returns>
+    /// <returns>A <see cref="Task{TResult}"/> that yields the matched <see cref="OptionList"/>, or <see langword="null"/> if no document/option is found or the operation fails.</returns>
     /// <!-- aidoc:v1 sig=fdb2628 body=0e4983e -->
     public async Task<OptionList?> FindOptionItemById(ObjectId masterId, ObjectId optionId, LocaleEnum locale)
     {
@@ -374,13 +374,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Finds a master list entity by its ID with optional locale translation for options.
+    /// Asynchronously finds an entity of type <typeparamref name="T"/> by its MongoDB <see cref="ObjectId"/>, executing an aggregation pipeline that unwinds the <c>options</c> array and resolves localized option names. When <paramref name="locale"/> is <c>null</c> or <see cref="LocaleEnum.Default"/>, the original option name is returned; otherwise, the option name is translated using the supplied locale, falling back to the original name when no matching <c>localeItems</c> entry exists. Returns <c>null</c> when no document is found or when an exception is caught and logged.
-    /// Uses MongoDB aggregation to unwind options and apply translations.
     /// </summary>
-    /// <param name="id">The ObjectId of the entity to retrieve.</param>
+    /// <param name="id">The MongoDB <see cref="ObjectId"/> that uniquely identifies the document to retrieve.</param>
-    /// <param name="locale">Optional locale for translated option names.</param>
+    /// <param name="locale">The optional <see cref="LocaleEnum"/> used to resolve translated option names; pass <c>null</c> or <see cref="LocaleEnum.Default"/> to use the default (non-translated) names.</param>
-    /// <returns>The MasterList entity with translated options if found; otherwise, null.</returns>
+    /// <returns>A <see cref="Task{T}"/> that yields the matched entity of type <typeparamref name="T"/>, or <c>null</c> if no document matches <paramref name="id"/> or if an error occurs during aggregation.</returns>
-    /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
     /// <!-- aidoc:v1 sig=cb4a658 body=f2e88d8 -->
     public async Task<T?> FindById(ObjectId id, LocaleEnum? locale)
     {
@@ -559,10 +557,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Asynchronously retrieves the first entity whose <c>Name</c> matches the supplied <paramref name="name"/>, applying a projection that caps the <c>options</c> array at 100 elements. If no document is found, or the query fails, the task resolves to <c>null</c>.
+    /// Asynchronously finds a single <typeparamref name="T"/> entity by its <see cref="T.Name"/> using a MongoDB query, projecting only the first 100 elements of the <c>options</c> field to limit payload size. Returns <c>null</c> if no matching document is found or if an error occurs during the search.
     /// </summary>
-    /// <param name="name">The value compared against the entity's <c>Name</c> property to build the equality filter.</param>
+    /// <param name="name">The name value used to build the equality filter against the entity's <c>Name</c> field.</param>
-    /// <returns>A <see cref="Task{T}"/> producing the first matching entity, or <c>null</c> when no match exists or the operation is aborted by a caught exception.</returns>
+    /// <returns>A <see cref="Task{T}"/> that yields the matching <typeparamref name="T"/> instance, or <c>null</c> when no document matches or the operation fails.</returns>
     /// <!-- aidoc:v1 sig=80a1541 body=8b5b558 -->
     public async Task<T?> FindByName(string name)
     {
@@ -599,10 +597,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Builds a paginated query against the master collection of <typeparamref name="T"/>, applying a case-insensitive substring match on the <see cref="PaginationFilter.FilteredRequest"/> text against the <c>Name</c> property when provided. Sorts results ascending by <c>name</c> and returns a fluent find interface so callers can continue chaining pagination or projection operations.
+    /// Retrieves paginated master lists with optional text filtering.
     /// </summary>
-    /// <param name="filter">The <see cref="PaginationFilter"/> containing pagination options and the optional <see cref="FilteredRequest.Text"/> used to match against <c>Name</c>.</param>
+    /// <param name="filter">The pagination and filtering parameters.</param>
-    /// <returns>An <see cref="IFindFluent{TDocument, TProjection}"/> representing the sorted (and optionally text-filtered) query, ready for further pagination configuration.</returns>
+    /// <returns>A fluent queryable for MasterList results.</returns>
     /// <!-- aidoc:v1 sig=bbb39c7 body=f42ebaa -->
     public IFindFluent<T, T> GetPaginatedMasterList(PaginationFilter filter)
     {
@@ -626,11 +624,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Retrieves paginated options within a master list with optional text filtering.
+    /// Retrieves the options belonging to the master list identified by <paramref name="listId"/>, optionally narrowed down by the text contained in <paramref name="filter"/>. Returns an empty collection when no master list exists for the given identifier, and when a non-empty filter text is supplied, applies a case-insensitive match against each option's name, description, or option type.
     /// </summary>
-    /// <param name="filter">The pagination and filtering parameters.</param>
+    /// <param name="filter">The <see cref="PaginationFilter"/> that provides the optional text used to filter the returned options.</param>
-    /// <param name="listId">The ObjectId of the master list.</param>
+    /// <param name="listId">The <see cref="ObjectId"/> of the master list whose options should be retrieved.</param>
-    /// <returns>A list of filtered OptionList items.</returns>
+    /// <returns>A <see cref="Task"/> that resolves to a <see cref="List{OptionList}"/> of options matching the filter, or an empty list when the master list cannot be found.</returns>
+    /// <!-- aidoc:v1 sig=2ac8d75 body=b25fb18 -->
     public async Task<List<OptionList>> GetPaginatedOptions(PaginationFilter filter, ObjectId listId)
     {
         //TODO: LOCALE
@@ -650,11 +649,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Adds a new <see cref="OptionList"/> entry to the master list identified by <paramref name="id"/>, returning <c>null</c> when an equivalent option already exists, the database update does not modify any document, or the operation fails.
+    /// Adds a new <see cref="OptionList"/> entry to the master list identified by <paramref name="id"/>. Returns the created option on success, or <c>null</c> if a matching option already exists, the master list cannot be retrieved, the update does not modify any document, or the operation throws an exception that is logged.
     /// </summary>
-    /// <param name="id">The <see cref="ObjectId"/> of the master list (document of type <c>T</c>) that will receive the new option.</param>
+    /// <param name="id">The <see cref="ObjectId"/> of the master list to update.</param>
-    /// <param name="opt">The <see cref="FilterOptionListElement"/> describing the option to add, including its name, optional visual properties, and locale information.</param>
+    /// <param name="opt">The <see cref="FilterOptionListElement"/> describing the option to add; its locale items are reused when <see cref="FilterOptionListElement.IsFromAdmPanel"/> is <c>true</c>, otherwise new locale entries are generated from the master list's <see cref="LocaleEnum"/> default.</param>
-    /// <returns>A <see cref="Task{T}"/> that yields the newly created <see cref="OptionList"/> when the push update succeeds, or <c>null</c> when a duplicate is detected, no document is modified, or an exception is logged and swallowed.</returns>
+    /// <returns>A <see cref="Task{OptionList}"/> that resolves to the newly created <see cref="OptionList"/> when the push update succeeds, or <c>null</c> when the operation is skipped, no document is modified, or the update fails.</returns>
     /// <!-- aidoc:v1 sig=1602f0d body=e7fd138 -->
     public async Task<OptionList?> AddOptionToMasterList(ObjectId id, FilterOptionListElement opt)
     {
@@ -695,10 +694,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Asynchronously retrieves all entities of type T from the underlying collection.
+    /// Asynchronously retrieves all entities from the underlying collection.
-    /// If an exception occurs during retrieval, the error is logged and an empty collection is returned as a fallback.
+    /// If an exception occurs during retrieval, the error is logged and an empty collection is returned rather than propagating the failure.
     /// </summary>
-    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="IEnumerable{T}"/> of all entities, or an empty collection if an error was encountered.</returns>
+    /// <returns>A <see cref="Task"/> that yields an <see cref="IEnumerable{T}"/> containing all retrieved entities, or an empty collection if the operation fails.</returns>
     /// <!-- aidoc:v1 sig=3a61c61 body=40d7129 -->
     public async Task<IEnumerable<T>> GetAll()
     {
@@ -715,12 +714,9 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Retrieves all master lists from the underlying collection and projects each entity into a <see cref="MasterListDto"/>,
+    /// Retrieves all master list entries from the underlying collection without applying any filter and projects each result into a <see cref="MasterListDto"/>, where the <see cref="MasterListDto.Options"/> property is set to the count of associated options rather than the option list itself.
-    /// where the <see cref="MasterListDto.Options"/> field holds the count of associated options instead of the full options collection.
-    /// If the operation fails, the exception is logged and an empty collection is returned.
     /// </summary>
-    /// <returns>A task that represents the asynchronous operation, yielding an <see cref="IEnumerable{MasterListDto}"/> of all
+    /// <returns>A <see cref="Task"/> that resolves to an <see cref="IEnumerable{T}"/> containing the projected <see cref="MasterListDto"/> instances, or an empty collection if an error is encountered while querying the data store.</returns>
-    /// projected master lists, or an empty collection if an error occurs.</returns>
     /// <!-- aidoc:v1 sig=e493435 body=1c299ba -->
     public async Task<IEnumerable<MasterListDto>> GetAllWithoutOptions()
     {
@@ -746,9 +742,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Asynchronously counts all entities in the collection by invoking <c>CountDocumentsAsync</c> with a filter that matches every document. If the operation fails, the exception is logged and the method returns <c>0</c> as a safe fallback.
+    /// Asynchronously counts all entities in the underlying <see cref="Collection"/> by invoking
+    /// <c>CountDocumentsAsync</c> with a filter that matches every document. If the operation fails,
+    /// the exception is logged via <c>Log.Error</c> and the method returns <c>0</c> as a safe fallback.
     /// </summary>
-    /// <returns>A <see cref="Task{Int32}"/> that yields the total number of entities, or <c>0</c> if an error occurs.</returns>
+    /// <returns>A <see cref="Task{Int32}"/> that represents the asynchronous count operation. The result
+    /// is the total number of entities, or <c>0</c> if an error occurred while querying the collection.</returns>
     /// <!-- aidoc:v1 sig=f1f0a98 body=01cd3d1 -->
     public async Task<int> Count()
     {
@@ -765,12 +764,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Retrieves the options of a master list identified by <paramref name="id"/>, applying the supplied <paramref name="filters"/> and resolving localized names and descriptions for the requested locale.
+    /// Retrieves the options of a master list identified by <paramref name="id"/>, applying the optional <paramref name="filters"/> to restrict the results by option type, text, name, or description, and resolving the localized <c>name</c> and <c>description</c> fields for each option based on the requested locale. When <paramref name="filters"/> is <c>null</c>, no options are returned. Text searches are performed case-insensitively against both the name and description of each option using a normalized pattern, and the final result is ordered alphabetically by name. Any exception during execution is logged and an empty list is returned.
-    /// When <paramref name="filters"/> is <c>null</c>, or when the aggregation yields no document, an empty list is returned; any exception is logged and also results in an empty list.
     /// </summary>
-    /// <param name="id">The <see cref="ObjectId"/> of the master list to retrieve.</param>
+    /// <param name="id">The <see cref="ObjectId"/> of the master list whose options will be queried.</param>
-    /// <param name="filters">The optional <see cref="FilterOptionListElement"/> that defines the search criteria (option type, text, name, and description) and the target locale used to translate each option.</param>
+    /// <param name="filters">Optional <see cref="FilterOptionListElement"/> containing the search criteria (option type, text, name, description, and locale). When <c>null</c>, the method returns an empty list.</param>
-    /// <returns>A <see cref="Task{List{OptionList}}"/> of <see cref="OptionList"/> entries matching the filters, ordered by name, or an empty list when no results are found.</returns>
+    /// <returns>A <see cref="Task{List{OptionList}}"/> containing the filtered, localized, and alphabetically ordered options; an empty list is returned when no filters are provided, no options match, or an error occurs.</returns>
     /// <!-- aidoc:v1 sig=f6ee5be body=17d6a96 -->
     public async Task<List<OptionList>> GetMasterListByIdAndSearchOptions(ObjectId id, FilterOptionListElement? filters)
     {
@@ -980,13 +978,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Updates a specific option within a master list with locale-aware field updates.
+    /// Updates an option within a master list, handling duplicate detection, locale-specific translations, and conditional field updates based on the master list's required field rules.
     /// </summary>
-    /// <param name="id">The ObjectId of the master list.</param>
+    /// <param name="id">The <see cref="MongoDB.Bson.ObjectId"/> of the master list that contains the option to update.</param>
-    /// <param name="newOpt">The OptionList with updated values.</param>
+    /// <param name="newOpt">The <see cref="OptionList"/> containing the new values to apply to the existing option.</param>
-    /// <param name="locale">The locale for translation updates.</param>
+    /// <param name="locale">The <see cref="LocaleEnum"/> indicating which locale the <paramref name="newOpt"/> applies to; when it matches the master's default locale, the main field is updated, otherwise the translation stored in <c>localeItems</c> is updated.</param>
-    /// <returns>The updated OptionList if successful; otherwise, null.</returns>
+    /// <returns>A <see cref="Task{T}"/> containing the updated <see cref="OptionList"/>, the existing option when a duplicate is detected, or <c>null</c> when the option is not found, no fields qualify for update, or the update operation fails.</returns>
-    /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
     /// <!-- aidoc:v1 sig=e771f23 body=5520a4a -->
     public async Task<OptionList?> UpdateMasterListOption(ObjectId id, OptionList newOpt, LocaleEnum locale)
     {
@@ -1082,12 +1079,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Updates a specific option within a master list with full replacement.
+    /// Updates an existing option inside the master list identified by <paramref name="id"/> with the data from <paramref name="newOpt"/>. Returns <see langword="null"/> when the master list is not found, when no document is modified, or when an exception is caught and logged.
     /// </summary>
-    /// <param name="id">The ObjectId of the master list.</param>
+    /// <param name="id">The <see cref="ObjectId"/> of the master list that owns the option to update.</param>
-    /// <param name="newOpt">The OptionList with updated values.</param>
+    /// <param name="newOpt">The <see cref="OptionList"/> whose <see cref="ObjectId"/> targets the option to replace and whose values are persisted to the document.</param>
-    /// <returns>The updated OptionList if successful; otherwise, null.</returns>
+    /// <returns>A task containing the updated <see cref="OptionList"/> when the update succeeds, or <see langword="null"/> when the master list is missing, nothing was modified, or the update failed.</returns>
-    /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
     /// <!-- aidoc:v1 sig=6def54c body=9554543 -->
     public async Task<OptionList?> UpdateMasterListOption(ObjectId id, OptionList newOpt)
     {
@@ -1143,11 +1139,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Updates the option details of an existing master list entry identified by <paramref name="id"/>, applying only the fields from <paramref name="opt"/> that are not <see langword="null"/> (currently <see cref="UpdateMasterListDetailsDto.CanAddElement"/> and <see cref="UpdateMasterListDetailsDto.OptionListDetails"/>).
+    /// Updates the option details of a master list document identified by <paramref name="id"/>, persisting only the non-null fields supplied in <paramref name="opt"/>.
     /// </summary>
-    /// <param name="id">The <see cref="ObjectId"/> of the document to update in the collection.</param>
+    /// <param name="id">The <see cref="ObjectId"/> of the master list entry to update.</param>
-    /// <param name="opt">The <see cref="UpdateMasterListDetailsDto"/> carrying the new values; <see langword="null"/> properties are left unchanged.</param>
+    /// <param name="opt">The <see cref="UpdateMasterListDetailsDto"/> whose non-null <see cref="UpdateMasterListDetailsDto.CanAddElement"/> and <see cref="UpdateMasterListDetailsDto.OptionListDetails"/> values are written to the document.</param>
-    /// <returns>The <paramref name="opt"/> instance if the document was found and modified; otherwise, <see langword="null"/> when the document was not found, no fields were modified, or the operation failed.</returns>
+    /// <returns>The supplied <see cref="UpdateMasterListDetailsDto"/> when at least one field is modified, or <see langword="null"/> when the document is not found, no changes are applied, or the operation fails.</returns>
     /// <!-- aidoc:v1 sig=53d4179 body=49f50ca -->
     public async Task<UpdateMasterListDetailsDto?> UpdateOptionDetailsToMasterList(ObjectId id,
         UpdateMasterListDetailsDto opt)
@@ -1178,11 +1174,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Updates the name of a master list entry identified by <paramref name="id"/> in the underlying collection. Returns <c>true</c> when the document was modified, or <c>false</c> if no document matched the identifier or an exception was caught and logged.
+    /// Updates the name of the master list document identified by <paramref name="id"/>.
+    /// Returns <c>true</c> if a document was modified, <c>false</c> if no document matched the id or if an exception was caught and logged.
     /// </summary>
-    /// <param name="id">The <see cref="ObjectId"/> of the master list document to update.</param>
+    /// <param name="id">The <see cref="MongoDB.Bson.ObjectId"/> of the master list entry to update.</param>
-    /// <param name="name">The new name to assign to the master list entry.</param>
+    /// <param name="name">The new name to assign to the entry.</param>
-    /// <returns><c>true</c> if a document was modified; otherwise, <c>false</c>.</returns>
+    /// <returns>A <see cref="Task{Boolean}"/> that resolves to <c>true</c> when the update modified a document; otherwise, <c>false</c>.</returns>
     /// <!-- aidoc:v1 sig=5b79a51 body=36dfe99 -->
     public async Task<bool> UpdateMasterListName(ObjectId id, string name)
     {
@@ -1204,11 +1201,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Updates the description of a master list entry identified by <paramref name="id"/> in the MongoDB collection, returning <see langword="true"/> when a document was modified and <see langword="false"/> when no document matched or a caught <see cref="Exception"/> was logged.
+    /// Updates the <see cref="T.Description"/> field of the master list entry identified by <paramref name="id"/>.
+    /// Returns <c>true</c> when the matched document is modified, and <c>false</c> when no document matches the filter or the underlying update operation throws, in which case the exception is logged and the call resolves to <c>false</c>.
     /// </summary>
     /// <param name="id">The <see cref="ObjectId"/> of the master list entry to update.</param>
-    /// <param name="description">The new description to set on the entry.</param>
+    /// <param name="description">The new description value to set on the entry.</param>
-    /// <returns>A <see cref="Task{Boolean}"/> that resolves to <see langword="true"/> if the update modified a document; otherwise, <see langword="false"/> when the entry was not found or an error was logged.</returns>
+    /// <returns>A <see cref="Task{Boolean}"/> that yields <c>true</c> if the update modified a document; otherwise, <c>false</c>.</returns>
     /// <!-- aidoc:v1 sig=5a27a55 body=3552f46 -->
     public async Task<bool> UpdateMasterListDescription(ObjectId id, string description)
     {
@@ -1230,11 +1228,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Removes the specified option from the master list document identified by <paramref name="id"/> by issuing a pull filter against the MongoDB collection that matches all of the option's properties (name, option type, icons, colors, default flag, and description). Returns true when the document is modified, or false if no match is found or if an exception is caught and logged.
+    /// Removes an option from a master list by matching all its properties.
     /// </summary>
-    /// <param name="id">The <see cref="ObjectId"/> of the master list document to update.</param>
+    /// <param name="id">The ObjectId of the master list.</param>
-    /// <param name="oldOpt">The <see cref="OptionList"/> whose property values define the filter used to locate and remove the matching element.</param>
+    /// <param name="oldOpt">The OptionList to remove.</param>
-    /// <returns>A <see cref="Task{Boolean}"/> that resolves to true if the document was modified; otherwise, false.</returns>
+    /// <returns>True if the option was removed; otherwise, false.</returns>
+    /// <exception cref="Exception">Logs errors and returns false on failure.</exception>
     /// <!-- aidoc:v1 sig=8de50cd body=d974b9b -->
     public async Task<bool> RemoveMasterListOption(ObjectId id, OptionList oldOpt)
     {
@@ -1264,8 +1263,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Overrides the base index creation to build non-unique, background MongoDB indexes on the <c>options.name</c>, <c>options.description</c>, and <c>options._id</c> fields of the <see cref="DiagnosisList"/> collection, configuring Spanish as the default and override language for text tokenization. The logic only runs when <typeparamref name="T"/> is <see cref="DiagnosisList"/>; for any other type the method is a no-op.
+    /// Creates background MongoDB indexes on the <see cref="DiagnosisList"/> collection to optimize queries against the nested <c>options</c> document fields, configuring the indexes with <c>spanish</c> as both the default and override language for text indexing.
     /// </summary>
+    /// <remarks>
+    /// When the generic type parameter is not <see cref="DiagnosisList"/>, the method performs no actions and returns without creating any indexes.
+    /// </remarks>
     /// <!-- aidoc:v1 sig=4955da2 body=2c8d1f7 -->
     public override async Task CreateIndexes()
     {
@@ -1378,11 +1380,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Creates a find fluent query that applies the provided <paramref name="filters"/> combined with a logical AND, falling back to an empty filter (matching all documents) when no filters are supplied, and orders the results by the specified <paramref name="sort"/>.
+    /// Creates a find query against the underlying collection by combining the provided <paramref name="filters"/> with a logical AND and applying the specified <paramref name="sort"/>. When the filter list is empty, an empty filter is used so that the query matches every document.
     /// </summary>
-    /// <param name="filters">A list of <see cref="FilterDefinition{T}"/> criteria to combine. When empty, an empty filter is used so that all documents match.</param>
+    /// <param name="filters">The list of <see cref="FilterDefinition{T}"/> predicates to combine; an empty list causes no filtering to be applied.</param>
-    /// <param name="sort">The <see cref="SortDefinition{T}"/> that defines the ordering of the returned documents.</param>
+    /// <param name="sort">The <see cref="SortDefinition{T}"/> used to order the returned documents.</param>
-    /// <returns>An <see cref="IFindFluent{T,T}"/> configured with the combined filter and the given sort.</returns>
+    /// <returns>An <see cref="IFindFluent{T,T}"/> configured with the combined filter and sort, ready for further chaining.</returns>
     /// <!-- aidoc:v1 sig=704d715 body=2a35652 -->
     private IFindFluent<T, T> CreateFindFluent(List<FilterDefinition<T>> filters, SortDefinition<T> sort)
     {
@@ -1393,11 +1395,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Creates a new <see cref="Locale"/> instance populated with <see cref="LocaleItem"/> entries for every <see cref="LocaleEnum"/> value except <see cref="LocaleEnum.Default"/> and the locale specified by <paramref name="localeList"/>. Each property of <see cref="Locale"/> matching an included enum name is dynamically assigned a new <see cref="LocaleItem"/> whose <see cref="LocaleItem.Name"/> is set to the value of <paramref name="opt"/>.
+    /// Generates new locale items for a master list option based on a default locale.
+    /// Creates LocaleItem entries for all locales except the specified default.
     /// </summary>
-    /// <param name="localeList">The locale to exclude from the generated <see cref="Locale"/> object.</param>
+    /// <param name="localeList">The default locale to exclude from translations.</param>
-    /// <param name="opt">The name assigned to every <see cref="LocaleItem"/> created in the resulting <see cref="Locale"/>.</param>
+    /// <param name="opt">The option name to use as default translation.</param>
-    /// <returns>A new <see cref="Locale"/> object containing the corresponding <see cref="LocaleItem"/> entries.</returns>
+    /// <returns>A Locale object with translations for all other locales.</returns>
     /// <!-- aidoc:v1 sig=147db59 body=9b63847 -->
     private Locale GetNewItemLocale(LocaleEnum localeList, string opt)
     {
@@ -1472,12 +1475,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     }
 
     /// <summary>
-    /// Retrieves the options of a master list document identified by <paramref name="id"/>, filtering them by the option name <paramref name="newOptName"/> resolved against the specified <paramref name="locale"/>. When the requested locale differs from the document's default locale, the method attempts to use the translated name; if no translation exists, it falls back to the original name. Returns an empty list when no document is found, when no options match, or when an error is logged.
+    /// Asynchronously retrieves a filtered list of <see cref="OptionList"/> entries from the master collection by matching the document with the specified <paramref name="id"/> and filtering options whose resolved name equals <paramref name="newOptName"/> for the given <paramref name="locale"/>. When the requested locale differs from the document's default, the pipeline uses the translated name from <c>localeItems</c>, falling back to the original name if no translation is available. Returns an empty list if no matching options are found or if an exception is logged during execution.
     /// </summary>
-    /// <param name="id">The <see cref="ObjectId"/> of the master list document to match in the aggregation pipeline.</param>
+    /// <param name="id">The <see cref="ObjectId"/> identifying the master document to aggregate.</param>
-    /// <param name="newOptName">The option name to filter by after the locale-based name resolution.</param>
+    /// <param name="newOptName">The option name used to filter the options after locale-based name resolution.</param>
-    /// <param name="locale">The <see cref="LocaleEnum"/> value used to select the translated name; the matching translation key is derived from its lowercased string representation.</param>
+    /// <param name="locale">The <see cref="LocaleEnum"/> value used to select the translated name for each option.</param>
-    /// <returns>A <see cref="Task{T}"/> of <see cref="List{T}"/> of <see cref="OptionList"/> containing the matching options ordered by name, or an empty list when nothing is found or an exception occurs.</returns>
+    /// <returns>A <see cref="Task"/> containing a <see cref="List{T}"/> of <see cref="OptionList"/> entries ordered by name, or an empty list when no match exists or an error is caught.</returns>
     /// <!-- aidoc:v1 sig=342dc63 body=21f31fc -->
     private async Task<List<OptionList>> GetMasterListByIdAndTextSearch(
         ObjectId id, string newOptName, LocaleEnum locale)

adas-core.LdapLogin/LdapLoginService.cs

@@ -78,13 +78,13 @@ public class LdapLoginService : ILoginService
     public UserEnum.LoginMethod Method => UserEnum.LoginMethod.Ldap;
 
     /// <summary>
-    /// Authenticates a user against the configured LDAP server using <paramref name="username"/> and <paramref name="password"/>, and resolves the matching <see cref="User"/> entry. When an LDAP service account is configured it is used for the bind; otherwise the username is optionally prefixed with the configured domain and bound with the supplied password. Searches the directory for the user entry and creates or retrieves the local <see cref="User"/> record.
+    /// Authenticates a user against the LDAP server using the provided username and password.
     /// </summary>
-    /// <param name="username">The username used to bind to LDAP and to locate the user entry in the directory.</param>
+    /// <param name="username">The username of the user to authenticate.</param>
-    /// <param name="password">The password used for the LDAP bind when no service account is configured.</param>
+    /// <param name="password">The password of the user to authenticate.</param>
-    /// <returns>The <see cref="User"/> resolved from the LDAP directory entry.</returns>
+    /// <returns>The authenticated user.</returns>
-    /// <exception cref="LoginServicesException">Thrown when the LDAP server is not configured, when the directory entry is not found, or when the resolved user is null.</exception>
+    /// <exception cref="LoginServicesException">Thrown when there is an error during the login process.</exception>
-    /// <exception cref="UserNotFoundException">Thrown when the LDAP bind fails for the supplied credentials.</exception>
+    /// <exception cref="UserNotFoundException">Thrown when the user is not found in the LDAP directory.</exception>
     /// <!-- aidoc:v1 sig=bdfb451 body=e3fc1ac -->
     public async Task<User> Login(string username, string password)
     {
@@ -157,24 +157,22 @@ public class LdapLoginService : ILoginService
     }
 
     /// <summary>
-    /// Authenticates a user based on the current <see cref="HttpContext"/>.
+    /// This method is not implemented in the LdapLoginService, as the login process is handled through the Login(string username, string password) method.
-    /// This method is not yet implemented and always throws a <see cref="LoginServicesException"/>.
     /// </summary>
-    /// <param name="context">The <see cref="HttpContext"/> of the incoming HTTP request used to extract authentication information.</param>
+    /// <param name="context">The HTTP context of the request.</param>
-    /// <returns>A <see cref="Task{TResult}"/> that resolves to the authenticated user.</returns>
+    /// <returns>A task representing the asynchronous operation.</returns>
-    /// <exception cref="LoginServicesException">Always thrown because the method is not implemented.</exception>
+    /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
     /// <!-- aidoc:v1 sig=851dc90 -->
     public Task<User> Login(HttpContext context)
         => throw new LoginServicesException("Not implemented");
 
     /// <summary>
-    /// Authenticates a user with the provided <paramref name="username"/> and <paramref name="password"/> and returns the corresponding <see cref="User"/>.
+    /// This method is not implemented in the LdapLoginService, as the authentication process is handled through the Login(string username, string password) method.
-    /// This method is not implemented and always throws a <see cref="LoginServicesException"/> when invoked.
     /// </summary>
     /// <param name="username">The username of the user to authenticate.</param>
     /// <param name="password">The password of the user to authenticate.</param>
-    /// <returns>A <see cref="Task{User}"/> that yields the authenticated <see cref="User"/>.</returns>
+    /// <returns>A task representing the asynchronous operation.</returns>
-    /// <exception cref="LoginServicesException">Thrown because authentication is not implemented.</exception>
+    /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
     /// <!-- aidoc:v1 sig=a0b1f46 -->
     public Task<User> Authenticate(string username, string password)
         => throw new LoginServicesException("Not implemented");
@@ -200,20 +198,20 @@ public class LdapLoginService : ILoginService
         => throw new LoginServicesException("Not implemented");
 
     /// <summary>
-    /// This method is not implemented in the LdapLoginService, as the user retrieval process is handled through the Login(string username, string password) method and the GetOrCreateUser(User userEntryLdap, LdapEntry entry) method.
+    /// Retrieves a <see cref="User"/> matching the specified <paramref name="username"/>.
     /// </summary>
-    /// <param name="username">The username of the user to retrieve.</param>
+    /// <param name="username">The username to look up.</param>
-    /// <returns>A task representing the asynchronous operation.</returns>
+    /// <returns>A <see cref="Task{TResult}"/> that resolves to the <see cref="User"/> if found, or <see langword="null"/> when no matching user exists.</returns>
-    /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <exception cref="LoginServicesException">Thrown because the operation is not yet implemented.</exception>
     /// <!-- aidoc:v1 sig=5184c30 -->
     public Task<User?> GetByUsername(string username)
         => throw new LoginServicesException("Not implemented");
 
     /// <summary>
-    /// This method is not implemented in the LdapLoginService, as the user retrieval process is handled through the Login(string username, string password) method and the GetOrCreateUser(User userEntryLdap, LdapEntry entry) method.
+    /// Retrieves all <see cref="User"/> entities from the system. This method is not yet implemented and currently throws a <see cref="LoginServicesException"/> when invoked.
     /// </summary>
-    /// <returns>A task representing the asynchronous operation.</returns>
+    /// <returns>A <see cref="Task{List{User}}"/> that represents the asynchronous operation, intended to contain the full collection of <see cref="User"/> entries.</returns>
-    /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <exception cref="LoginServicesException">Thrown unconditionally because the method has not been implemented.</exception>
     /// <!-- aidoc:v1 sig=aa066d6 -->
     public Task<List<User>> GetAllUsers()
         => throw new LoginServicesException("Not implemented");
@@ -246,13 +244,11 @@ public class LdapLoginService : ILoginService
 
 
     /// <summary>
-    /// Synchronizes the authorities of a <paramref name="user"/> with the authorities defined in the supplied <paramref name="entry"/>, updating existing records or inserting new ones as appropriate.
+    /// This method checks the authorities of a user based on the LDAP entry and the application's configuration.
-    /// Authorities appearing in the whitelist are preserved and excluded from the LDAP map, while remaining LDAP authorities are compared against the current persisted list; entries with <see cref="Authorization.CanUpdate"/> set to <c>true</c> have their <see cref="Authorization.Rol"/> refreshed via <see cref="AuthorityService.updateOne"/>, otherwise they are inserted with <see cref="AuthorityService.InsertOne"/>.
-    /// On any failure, the error is logged and an empty list is returned.
     /// </summary>
-    /// <param name="user">The user whose authorities are being reconciled.</param>
+    /// <param name="user">The user whose authorities are being checked.</param>
-    /// <param name="entry">The <see cref="LdapEntry"/> providing the source authorities map and whitelist.</param>
+    /// <param name="entry">The LDAP entry containing the user's information.</param>
-    /// <returns>The updated <see cref="Authorization"/> list retrieved from the authority service.</returns>
+    /// <returns>A list of updated authorities for the user.</returns>
     /// <!-- aidoc:v1 sig=d2bafd5 body=4af15eb -->
     private async Task<List<Authorization>> CheckAuthorities(User user, LdapEntry entry)
 
@@ -343,12 +339,10 @@ public class LdapLoginService : ILoginService
 
 
     /// <summary>
-    /// Maps the supplied <see cref="LdapEntry"/> to a <see cref="User"/> instance by reading attributes whose names are configured in the LDAP settings.
+    /// Maps an <see cref="LdapEntry"/> to a <see cref="User"/> object, populating the username from the configured attribute and, when the corresponding properties are configured, composing the user's name from the first and last name attributes.
-    /// The <see cref="User.UserName"/> is taken from the configured user name property, falling back to an empty string when the attribute is absent.
-    /// When the first name and/or last name properties are configured, their attribute values are used to build the <see cref="User.Name"/>; otherwise the name is left unset, and the last name is appended to the first name when both are present.
     /// </summary>
-    /// <param name="ldapEntry">The <see cref="LdapEntry"/> whose attributes are read to populate the resulting <see cref="User"/>.</param>
+    /// <param name="ldapEntry">The <see cref="LdapEntry"/> from which the <see cref="User"/> properties are read.</param>
-    /// <returns>A <see cref="User"/> populated from the attributes exposed by <paramref name="ldapEntry"/> according to the current LDAP configuration.</returns>
+    /// <returns>A <see cref="User"/> instance populated from the LDAP entry attributes.</returns>
     /// <!-- aidoc:v1 sig=947181a body=33ffec8 -->
     private User GetUser(LdapEntry ldapEntry)