From c9446ed5d7dba0303ac01083235dc53c0d8c9c62 Mon Sep 17 00:00:00 2001
From: n8n IEC 62304 Bot <n8n-iec62304-bot@local>
Date: Mon, 6 Jul 2026 19:09:40 +0200
Subject: [PATCH] docs(iec62304): [REL-1.0.2] validate and curate XML doc
 review markers

---
 .../Repositories/MasterListRepository.cs       | 18 ++++++++++++++++++
 adas-core.LdapLogin/LdapLoginService.cs        |  4 ++++
 2 files changed, 22 insertions(+)

diff --git a/adas-core.Infrastructure/Repositories/MasterListRepository.cs b/adas-core.Infrastructure/Repositories/MasterListRepository.cs
index 5cddb35d..4a4b3aa1 100644
--- a/adas-core.Infrastructure/Repositories/MasterListRepository.cs
+++ b/adas-core.Infrastructure/Repositories/MasterListRepository.cs
@@ -173,6 +173,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="id">The <see cref="ObjectId"/> used to build the equality filter against the entity's identifier.</param>
     /// <returns>A <see cref="Task{T}"/> that yields the matching entity, or <c>null</c> when no document is found or the operation fails.</returns>
     /// <!-- aidoc:v1 sig=81ac96a body=1519944 -->
+    /// <!-- aidoc-review:v1 severity=low kind=wrong_summary
+    ///      "The summary implies that 'the error is logged' in both the no-match and exception cases, but the code only logs in the catch block; FirstOrDefaultAsync returning null is not logged." -->
     public async Task<T?> FindById(ObjectId id)
     {
         try
@@ -349,6 +351,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <returns>The OptionList if found; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
     /// <!-- aidoc:v1 sig=ccc34cb body=71837cc -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_exception
+    ///      "The method catches all exceptions and returns null rather than throwing; the <exception cref=\"Exception\"> tag is misleading because the method does not propagate any exception to its caller." -->
     public async Task<OptionList?> FindOptionItemById(ObjectId masterId, ObjectId optionId)
     {
         try
@@ -605,6 +609,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="filter">The <see cref="PaginationFilter"/> containing the optional <c>FilteredRequest.Text</c> used to match the <c>Name</c> field.</param>
     /// <returns>An <see cref="IFindFluent{TDocument, TProjection}"/> representing the sorted, filtered query against the collection of <typeparamref name="T"/>.</returns>
     /// <!-- aidoc:v1 sig=bbb39c7 body=f42ebaa -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary claims that if 'filter' is null no additional filter is applied and the unfiltered, sorted result is returned, but the code accesses 'filter.FilteredRequest' without a null check and would throw a NullReferenceException when 'filter' is null." -->
     public IFindFluent<T, T> GetPaginatedMasterList(PaginationFilter filter)
     {
         var filterBuilder = Builders<T>.Filter;
@@ -776,6 +782,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <returns>A list of matching OptionList items ordered by name.</returns>
     /// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
     /// <!-- aidoc:v1 sig=f6ee5be body=17d6a96 -->
+    /// <!-- aidoc-review:v1 severity=medium kind=extra_exception
+    ///      "The method catches every Exception in its body and returns an empty list; it does not throw Exception to callers, so the <exception> tag is misleading." -->
+    /// <!-- aidoc-review:v1 severity=medium kind=missing_param
+    ///      "filters.Locale is used in the aggregation pipeline to drive locale-based translations but is not mentioned in the <param name=\"filters\"> description." -->
     public async Task<List<OptionList>> GetMasterListByIdAndSearchOptions(ObjectId id, FilterOptionListElement? filters)
     {
         try
@@ -992,6 +1002,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <returns>The updated OptionList if successful; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
     /// <!-- aidoc:v1 sig=e771f23 body=5520a4a -->
+    /// <!-- aidoc-review:v1 severity=medium kind=extra_exception
+    ///      "The method catches Exception and does not re-throw it; the <exception> tag documents caught-and-handled behavior as if it were a thrown exception, which is non-standard and misleading." -->
     public async Task<OptionList?> UpdateMasterListOption(ObjectId id, OptionList newOpt, LocaleEnum locale)
     {
         // 1. Evitar duplicados
@@ -1093,6 +1105,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <returns>The updated OptionList if successful; otherwise, null.</returns>
     /// <exception cref="Exception">Logs errors and returns null on failure.</exception>
     /// <!-- aidoc:v1 sig=6def54c body=9554543 -->
+    /// <!-- aidoc-review:v1 severity=medium kind=extra_exception
+    ///      "<exception cref=\"Exception\"> is documented but the method catches all exceptions internally and never rethrows them; the tag should be removed or rephrased to describe the catch behavior." -->
     public async Task<OptionList?> UpdateMasterListOption(ObjectId id, OptionList newOpt)
     {
         var master = await FindById(id);
@@ -1317,6 +1331,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <returns>A list of matching OptionList items ordered by name.</returns>
     /// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
     /// <!-- aidoc:v1 sig=6ebeac8 body=1d7bbb7 -->
+    /// <!-- aidoc-review:v1 severity=medium kind=extra_exception
+    ///      "The method wraps the body in a try-catch that catches Exception and returns an empty list, so it never throws Exception to the caller; documenting it via <exception> is misleading." -->
     private async Task<List<OptionList>> GetOptionsByTextSearch(string? textSearch, ObjectId? id = null)
     {
         try
@@ -1495,6 +1511,8 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
     /// <param name="locale">The <see cref="LocaleEnum"/> value used to select the translated name for each option.</param>
     /// <returns>A <see cref="Task"/> containing a <see cref="List{Object}"/> of matching options ordered by name, or an empty list when no options match or an error occurs.</returns>
     /// <!-- aidoc:v1 sig=342dc63 body=21f31fc -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_returns
+    ///      "The <returns> tag references List{Object}, but the method actually returns Task<List<OptionList>>." -->
     private async Task<List<OptionList>> GetMasterListByIdAndTextSearch(
         ObjectId id, string newOptName, LocaleEnum locale)
     {
diff --git a/adas-core.LdapLogin/LdapLoginService.cs b/adas-core.LdapLogin/LdapLoginService.cs
index 19a940d0..0d5b24ff 100644
--- a/adas-core.LdapLogin/LdapLoginService.cs
+++ b/adas-core.LdapLogin/LdapLoginService.cs
@@ -174,6 +174,8 @@ public class LdapLoginService : ILoginService
     /// <returns>A <see cref="Task{User}"/> that represents the asynchronous authentication operation, yielding the authenticated <see cref="User"/> on success.</returns>
     /// <exception cref="LoginServicesException">Thrown because the authentication operation is not yet implemented.</exception>
     /// <!-- aidoc:v1 sig=a0b1f46 -->
+    /// <!-- aidoc-review:v1 severity=low kind=wrong_returns
+    ///      "The returns description mentions yielding the authenticated User on success, but the method never reaches success since it always throws. Mitigated by the exception tag noting the not-implemented state." -->
     public Task<User> Authenticate(string username, string password)
         => throw new LoginServicesException("Not implemented");
 
@@ -194,6 +196,8 @@ public class LdapLoginService : ILoginService
     /// <returns>A <see cref="Task{T}"/> that resolves to the matching <see cref="User"/>, or <see langword="null"/> if no user exists for the given <paramref name="email"/>.</returns>
     /// <exception cref="LoginServicesException">Thrown because the operation is not implemented.</exception>
     /// <!-- aidoc:v1 sig=ba92b09 -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary and returns describe retrieving a User (or null), but the method body unconditionally throws LoginServicesException and never performs any lookup or returns a User." -->
     public Task<User?> GetByEmail(string email)
         => throw new LoginServicesException("Not implemented");