From ad518abd07c85802adf3c63dbfd8f1f1781aa8c2 Mon Sep 17 00:00:00 2001 From: n8n IEC 62304 Bot Date: Mon, 6 Jul 2026 21:21:05 +0200 Subject: [PATCH] docs(iec62304): [REL-1.0.2] apply curated XML doc review updates --- .../Repositories/MasterListRepository.cs | 239 +++++++----------- adas-core.LdapLogin/LdapLoginService.cs | 31 +-- 2 files changed, 109 insertions(+), 161 deletions(-) diff --git a/adas-core.Infrastructure/Repositories/MasterListRepository.cs b/adas-core.Infrastructure/Repositories/MasterListRepository.cs index 9b4745ef..2fada254 100644 --- a/adas-core.Infrastructure/Repositories/MasterListRepository.cs +++ b/adas-core.Infrastructure/Repositories/MasterListRepository.cs @@ -113,12 +113,11 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates an existing master list entity with full replacement. + /// Persists the supplied entity in the collection by replacing the document identified by , or inserting a new document when no match is found (upsert). Logs and rethrows any exception raised during the operation. /// - /// The entity with updated values. - /// Throws and re-throws exceptions after logging. - /// + /// The document type stored in the collection. + /// The entity whose locates the target document and whose state is written to the collection. + /// public async Task Update(T entity) { try @@ -168,17 +167,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a master list entity by its ID with options projection limited to 100 items. + /// Asynchronously retrieves an entity of type from the collection by its , applying a projection that truncates the options field to 100 elements. Returns when no matching document is found, or when an exception is caught and logged by . /// - /// The ObjectId of the entity to retrieve. - /// The MasterList entity if found; otherwise, null. - /// Logs errors and returns null on failure. - /// - /// - /// + /// The document type stored in the collection, expected to expose an identifier. + /// The of the entity to locate. + /// A that resolves to the matching entity, or if the document is not found or the operation fails. + /// public async Task FindById(ObjectId id) { try @@ -202,16 +196,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a specific option within a master list by master and option IDs with locale translation. - /// Uses MongoDB aggregation to apply translations and return the translated option. + /// Retrieves a single item from a master document identified by and , applying locale-aware name resolution. When is or matches the document's default locale, the base name is returned; otherwise, the matching entry from the localeItems map is used, falling back to the base name when no translation is found. Returns when the option is not found or if an error occurs during aggregation. /// - /// The ObjectId of the master list. - /// The ObjectId of the option to retrieve. - /// The locale for translation. - /// The OptionList with translated fields if found; otherwise, null. - /// Logs errors and returns null on failure. - /// + /// The of the master document that contains the option collection to search. + /// The of the specific option within the master document's options array. + /// The value that drives translation selection; resolves to the document's default locale, while any other value attempts a locale-specific lookup. + /// A that yields the matched , or if no document/option is found or the operation fails. + /// public async Task FindOptionItemById(ObjectId masterId, ObjectId optionId, LocaleEnum locale) { try @@ -383,17 +374,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a master list entity by its ID with optional locale translation for options. - /// Uses MongoDB aggregation to unwind options and apply translations. + /// Asynchronously finds an entity of type by its MongoDB , executing an aggregation pipeline that unwinds the options array and resolves localized option names. When is null or , 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 localeItems entry exists. Returns null when no document is found or when an exception is caught and logged. /// - /// The ObjectId of the entity to retrieve. - /// Optional locale for translated option names. - /// The MasterList entity with translated options if found; otherwise, null. - /// Logs errors and returns null on failure. - /// - /// + /// The MongoDB that uniquely identifies the document to retrieve. + /// The optional used to resolve translated option names; pass null or to use the default (non-translated) names. + /// A that yields the matched entity of type , or null if no document matches or if an error occurs during aggregation. + /// public async Task FindById(ObjectId id, LocaleEnum? locale) { try @@ -571,17 +557,11 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a master list entity by its name. + /// Asynchronously finds a single entity by its using a MongoDB query, projecting only the first 100 elements of the options field to limit payload size. Returns null if no matching document is found or if an error occurs during the search. /// - /// The name of the master list to retrieve. - /// The MasterList entity if found; otherwise, null. - /// Logs errors and returns null on failure. - /// - /// - /// + /// The name value used to build the equality filter against the entity's Name field. + /// A that yields the matching instance, or null when no document matches or the operation fails. + /// public async Task FindByName(string name) { try @@ -644,15 +624,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves paginated options within a master list with optional text filtering. + /// Retrieves the options belonging to the master list identified by , optionally narrowed down by the text contained in . 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. /// - /// The pagination and filtering parameters. - /// The ObjectId of the master list. - /// A list of filtered OptionList items. - /// - /// + /// The that provides the optional text used to filter the returned options. + /// The of the master list whose options should be retrieved. + /// A that resolves to a of options matching the filter, or an empty list when the master list cannot be found. + /// public async Task> GetPaginatedOptions(PaginationFilter filter, ObjectId listId) { //TODO: LOCALE @@ -672,14 +649,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Adds a new option to a master list. + /// Adds a new entry to the master list identified by . Returns the created option on success, or null 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. /// - /// The ObjectId of the master list. - /// The option element to add. - /// The newly created OptionList if successful; otherwise, null if duplicate exists. - /// Logs errors and returns null on failure. - /// + /// The of the master list to update. + /// The describing the option to add; its locale items are reused when is true, otherwise new locale entries are generated from the master list's default. + /// A that resolves to the newly created when the push update succeeds, or null when the operation is skipped, no document is modified, or the update fails. + /// public async Task AddOptionToMasterList(ObjectId id, FilterOptionListElement opt) { var exist = await GetMasterListByIdAndSearchOptions(id, opt); @@ -719,16 +694,11 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves all master list entities. + /// Asynchronously retrieves all entities from the underlying collection. + /// If an exception occurs during retrieval, the error is logged and an empty collection is returned rather than propagating the failure. /// - /// An enumerable of all MasterList entities. - /// Logs errors and returns empty list on failure. - /// - /// - /// + /// A that yields an containing all retrieved entities, or an empty collection if the operation fails. + /// public async Task> GetAll() { try @@ -744,12 +714,10 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves all master list entities without options, returning only metadata. + /// Retrieves all master list entries from the underlying collection without applying any filter and projects each result into a , where the property is set to the count of associated options rather than the option list itself. /// - /// An enumerable of MasterListDto containing id, name, description, listType, and options count. - /// Logs errors and returns empty list on failure. - /// + /// A that resolves to an containing the projected instances, or an empty collection if an error is encountered while querying the data store. + /// public async Task> GetAllWithoutOptions() { try @@ -774,12 +742,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Counts the total number of master list entities in the collection. + /// Asynchronously counts all entities in the underlying by invoking + /// CountDocumentsAsync with a filter that matches every document. If the operation fails, + /// the exception is logged via Log.Error and the method returns 0 as a safe fallback. /// - /// The total count of entities. - /// Logs errors and returns 0 on failure. - /// + /// A that represents the asynchronous count operation. The result + /// is the total number of entities, or 0 if an error occurred while querying the collection. + /// public async Task Count() { try @@ -795,17 +764,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Searches for options within a master list using multiple filter criteria. - /// Uses MongoDB aggregation pipeline to apply filters and locale translations. + /// Retrieves the options of a master list identified by , applying the optional to restrict the results by option type, text, name, or description, and resolving the localized name and description fields for each option based on the requested locale. When is null, 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. /// - /// The ObjectId of the master list. - /// The filter criteria including text, name, description, and optionType. - /// A list of matching OptionList items ordered by name. - /// Logs errors and returns empty list on failure. - /// - /// + /// The of the master list whose options will be queried. + /// Optional containing the search criteria (option type, text, name, description, and locale). When null, the method returns an empty list. + /// A 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. + /// public async Task> GetMasterListByIdAndSearchOptions(ObjectId id, FilterOptionListElement? filters) { try @@ -1014,15 +978,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// 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. /// - /// The ObjectId of the master list. - /// The OptionList with updated values. - /// The locale for translation updates. - /// The updated OptionList if successful; otherwise, null. - /// Logs errors and returns null on failure. - /// + /// The of the master list that contains the option to update. + /// The containing the new values to apply to the existing option. + /// The indicating which locale the applies to; when it matches the master's default locale, the main field is updated, otherwise the translation stored in localeItems is updated. + /// A containing the updated , the existing option when a duplicate is detected, or null when the option is not found, no fields qualify for update, or the update operation fails. + /// public async Task UpdateMasterListOption(ObjectId id, OptionList newOpt, LocaleEnum locale) { // 1. Evitar duplicados @@ -1117,14 +1079,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates a specific option within a master list with full replacement. + /// Updates an existing option inside the master list identified by with the data from . Returns when the master list is not found, when no document is modified, or when an exception is caught and logged. /// - /// The ObjectId of the master list. - /// The OptionList with updated values. - /// The updated OptionList if successful; otherwise, null. - /// Logs errors and returns null on failure. - /// + /// The of the master list that owns the option to update. + /// The whose targets the option to replace and whose values are persisted to the document. + /// A task containing the updated when the update succeeds, or when the master list is missing, nothing was modified, or the update failed. + /// public async Task UpdateMasterListOption(ObjectId id, OptionList newOpt) { var master = await FindById(id); @@ -1179,14 +1139,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates the metadata details for a master list. + /// Updates the option details of a master list document identified by , persisting only the non-null fields supplied in . /// - /// The ObjectId of the master list. - /// The UpdateMasterListDetailsDto with updated values. - /// The updated UpdateMasterListDetailsDto if successful; otherwise, null. - /// Logs errors and returns null on failure. - /// + /// The of the master list entry to update. + /// The whose non-null and values are written to the document. + /// The supplied when at least one field is modified, or when the document is not found, no changes are applied, or the operation fails. + /// public async Task UpdateOptionDetailsToMasterList(ObjectId id, UpdateMasterListDetailsDto opt) { @@ -1216,14 +1174,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates the name of a master list. + /// Updates the name of the master list document identified by . + /// Returns true if a document was modified, false if no document matched the id or if an exception was caught and logged. /// - /// The ObjectId of the master list. - /// The new name. - /// True if the update was successful; otherwise, false. - /// Logs errors and returns false on failure. - /// + /// The of the master list entry to update. + /// The new name to assign to the entry. + /// A that resolves to true when the update modified a document; otherwise, false. + /// public async Task UpdateMasterListName(ObjectId id, string name) { var filter = Builders.Filter.And( @@ -1244,14 +1201,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates the description of a master list. + /// Updates the field of the master list entry identified by . + /// Returns true when the matched document is modified, and false when no document matches the filter or the underlying update operation throws, in which case the exception is logged and the call resolves to false. /// - /// The ObjectId of the master list. - /// The new description. - /// True if the update was successful; otherwise, false. - /// Logs errors and returns false on failure. - /// + /// The of the master list entry to update. + /// The new description value to set on the entry. + /// A that yields true if the update modified a document; otherwise, false. + /// public async Task UpdateMasterListDescription(ObjectId id, string description) { var filter = Builders.Filter.And( @@ -1307,11 +1263,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Creates necessary indexes for the MasterList collection. - /// Currently creates text indexes for DiagnosisList on options.name, options.description, and options._id. + /// Creates background MongoDB indexes on the collection to optimize queries against the nested options document fields, configuring the indexes with spanish as both the default and override language for text indexing. /// - /// + /// + /// When the generic type parameter is not , the method performs no actions and returns without creating any indexes. + /// + /// public override async Task CreateIndexes() { if (typeof(T) == typeof(DiagnosisList)) @@ -1423,13 +1380,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Creates a fluent query for paginated results with combined filters. + /// Creates a find query against the underlying collection by combining the provided with a logical AND and applying the specified . When the filter list is empty, an empty filter is used so that the query matches every document. /// - /// List of filter definitions to apply. - /// Sort definition for the query results. - /// A fluent queryable for T results. - /// + /// The list of predicates to combine; an empty list causes no filtering to be applied. + /// The used to order the returned documents. + /// An configured with the combined filter and sort, ready for further chaining. + /// private IFindFluent CreateFindFluent(List> filters, SortDefinition sort) { var combinedFilter = filters.Any() @@ -1519,16 +1475,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Searches for options within a master list by name with locale translation. - /// Uses MongoDB aggregation pipeline to apply locale-aware filtering. + /// Asynchronously retrieves a filtered list of entries from the master collection by matching the document with the specified and filtering options whose resolved name equals for the given . When the requested locale differs from the document's default, the pipeline uses the translated name from localeItems, 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. /// - /// The ObjectId of the master list. - /// The option name to search for. - /// The locale for translation. - /// A list of matching OptionList items ordered by name. - /// Logs errors and returns empty list on failure. - /// + /// The identifying the master document to aggregate. + /// The option name used to filter the options after locale-based name resolution. + /// The value used to select the translated name for each option. + /// A containing a of entries ordered by name, or an empty list when no match exists or an error is caught. + /// private async Task> GetMasterListByIdAndTextSearch( ObjectId id, string newOptName, LocaleEnum locale) { diff --git a/adas-core.LdapLogin/LdapLoginService.cs b/adas-core.LdapLogin/LdapLoginService.cs index b35d2b3c..e0c89524 100644 --- a/adas-core.LdapLogin/LdapLoginService.cs +++ b/adas-core.LdapLogin/LdapLoginService.cs @@ -198,23 +198,21 @@ public class LdapLoginService : ILoginService => throw new LoginServicesException("Not implemented"); /// - /// 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 matching the specified . /// - /// The username of the user to retrieve. - /// A task representing the asynchronous operation. - /// Thrown when the method is not implemented. - /// + /// The username to look up. + /// A that resolves to the if found, or when no matching user exists. + /// Thrown because the operation is not yet implemented. + /// public Task GetByUsername(string username) => throw new LoginServicesException("Not implemented"); /// - /// 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 entities from the system. This method is not yet implemented and currently throws a when invoked. /// - /// A task representing the asynchronous operation. - /// Thrown when the method is not implemented. - /// + /// A that represents the asynchronous operation, intended to contain the full collection of entries. + /// Thrown unconditionally because the method has not been implemented. + /// public Task> GetAllUsers() => throw new LoginServicesException("Not implemented"); @@ -341,14 +339,11 @@ public class LdapLoginService : ILoginService /// - /// This method retrieves a list of authorities for a user based on the LDAP entry and the application's configuration for mapping LDAP groups to authorities. + /// Maps an to a 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 LDAP entry containing the user's information. - /// The existing or newly created user with updated authorities. - /// - /// + /// The from which the properties are read. + /// A instance populated from the LDAP entry attributes. + /// private User GetUser(LdapEntry ldapEntry) {