docs(iec62304): [REL-1.0.2] validate and curate XML doc review markers

adas-core.LdapLogin/LdapLoginService.cs

@@ -20,6 +20,7 @@ namespace adas_core.LdapLogin;
 /// The service also handles the creation of new users in the application if they do not already exist, based on the LDAP information. 
 /// It uses configuration settings for connecting to the LDAP server and for mapping LDAP attributes to user properties and authorities.
 /// </summary>
+/// <!-- aidoc:v1 sig=4e5637f -->
 public class LdapLoginService : ILoginService
 {
     /// <summary>
@@ -51,6 +52,7 @@ public class LdapLoginService : ILoginService
     /// <param name="userService">The user service for managing user information.</param>
     /// <param name="authorityService">The authority service for managing user authorities.</param>
     /// <param name="logger">The logger for logging LDAP login operations.</param>
+    /// <!-- aidoc:v1 sig=f1b8e4e body=6c4718f -->
     public LdapLoginService(
         IOptions<LdapConfig> ldapConfig,
         IValidator<LdapConfig> validator,
@@ -83,6 +85,8 @@ public class LdapLoginService : ILoginService
     /// <returns>The authenticated user.</returns>
     /// <exception cref="LoginServicesException">Thrown when there is an error during the login process.</exception>
     /// <exception cref="UserNotFoundException">Thrown when the user is not found in the LDAP directory.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_exception
+    ///      "UserNotFoundException is documented as thrown 'when the user is not found in the LDAP directory', but the code actually throws it from the catch (LdapException) block during the bind operation. The 'user not found in directory' case (empty search result) throws LoginServicesException, not UserNotFoundException." -->
     public async Task<User> Login(string username, string password)
     {
         if (_ldapConfig.Server == null)
@@ -159,6 +163,8 @@ public class LdapLoginService : ILoginService
     /// <param name="context">The HTTP context of the request.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=missing_returns
+    ///      "The <returns> description says 'A task representing the asynchronous operation' but the method returns Task<User>; the User element of the return type is not documented." -->
     public Task<User> Login(HttpContext context)
         => throw new LoginServicesException("Not implemented");
 
@@ -169,6 +175,8 @@ public class LdapLoginService : ILoginService
     /// <param name="password">The password of the user to authenticate.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=wrong_returns
+    ///      "The method returns Task<User>, but the documentation only states 'A task representing the asynchronous operation' without mentioning that the task produces a User." -->
     public Task<User> Authenticate(string username, string password)
         => throw new LoginServicesException("Not implemented");
 
@@ -178,6 +186,7 @@ public class LdapLoginService : ILoginService
     /// <param name="id">The ID of the user to retrieve.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc:v1 sig=877a869 -->
     public Task<User?> GetById(ObjectId id)
         => throw new LoginServicesException("Not implemented");
 
@@ -187,6 +196,7 @@ public class LdapLoginService : ILoginService
     /// <param name="email">The email of the user to retrieve.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc:v1 sig=ba92b09 -->
     public Task<User?> GetByEmail(string email)
         => throw new LoginServicesException("Not implemented");
 
@@ -196,6 +206,7 @@ public class LdapLoginService : ILoginService
     /// <param name="username">The username of the user to retrieve.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc:v1 sig=5184c30 -->
     public Task<User?> GetByUsername(string username)
         => throw new LoginServicesException("Not implemented");
 
@@ -204,6 +215,7 @@ public class LdapLoginService : ILoginService
     /// </summary>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
+    /// <!-- aidoc:v1 sig=aa066d6 -->
     public Task<List<User>> GetAllUsers()
         => throw new LoginServicesException("Not implemented");
 
@@ -215,6 +227,7 @@ public class LdapLoginService : ILoginService
     /// <param name="userEntryLdap">The user information obtained from the LDAP entry.</param>
     /// <param name="entry">The LDAP entry containing the user's information.</param>
     /// <returns>The existing or newly created user with updated authorities.</returns>
+    /// <!-- aidoc:v1 sig=87de1c2 body=a43bebd -->
     private async Task<User?> GetOrCreateUser(User userEntryLdap, LdapEntry entry)
 
     {
@@ -239,6 +252,8 @@ public class LdapLoginService : ILoginService
     /// <param name="user">The user whose authorities are being checked.</param>
     /// <param name="entry">The LDAP entry containing the user's information.</param>
     /// <returns>A list of updated authorities for the user.</returns>
+    /// <!-- aidoc-review:v1 severity=medium kind=stale_summary
+    ///      "Summary states the method 'checks' authorities, but the method actually synchronizes authorities: it updates existing entries (when CanUpdate is true) and inserts new ones via _authorityService, with side effects beyond a read-only check." -->
     private async Task<List<Authorization>> CheckAuthorities(User user, LdapEntry entry)
 
     {
@@ -289,6 +304,7 @@ public class LdapLoginService : ILoginService
     /// <param name="entry">The LDAP entry containing the user's information.</param>
     /// <param name="user">The user whose authorities are being retrieved.</param>
     /// <returns>A list of authorities for the user based on the whitelist.</returns>
+    /// <!-- aidoc:v1 sig=a8263f0 body=9e6cc38 -->
     private List<Authorization> GetAuthoritiesWhiteList(LdapEntry entry, User user)
 
     {
@@ -331,6 +347,10 @@ public class LdapLoginService : ILoginService
     /// </summary>
     /// <param name="ldapEntry">The LDAP entry containing the user's information.</param>
     /// <returns>The existing or newly created user with updated authorities.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary claims the method retrieves a list of authorities and maps LDAP groups to authorities, but the method actually constructs a User object using username, first name, and last name properties from the LDAP entry." -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_returns
+    ///      "The <returns> tag claims to return an 'existing or newly created user with updated authorities', but the method always creates a new User and never touches authorities." -->
     private User GetUser(LdapEntry ldapEntry)
 
     {
@@ -365,6 +385,7 @@ public class LdapLoginService : ILoginService
     /// <param name="ldapEntry">The LDAP entry containing the user's information.</param>
     /// <param name="user">The user whose authorities are being retrieved.</param>
     /// <returns>A list of authorities for the user based on the LDAP entry and the application's configuration.</returns>
+    /// <!-- aidoc:v1 sig=1e1f0f2 body=18015c0 -->
     private List<Authorization> GetAuthoritiesMap(LdapEntry ldapEntry, User user)
 
     {