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,7 @@ 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:v1 sig=bdfb451 body=e3fc1ac -->
     public async Task<User> Login(string username, string password)
     {
         if (_ldapConfig.Server == null)
@@ -159,6 +162,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=high kind=wrong_returns
+    ///      "The method returns Task<User> but the documentation only says 'A task representing the asynchronous operation' without mentioning the User return type, misleading readers about the actual return contract." -->
     public Task<User> Login(HttpContext context)
         => throw new LoginServicesException("Not implemented");
 
@@ -169,6 +174,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 <returns> tag says 'A task representing the asynchronous operation' but the method returns Task<User>; the documented return type omits the User result." -->
     public Task<User> Authenticate(string username, string password)
         => throw new LoginServicesException("Not implemented");
 
@@ -178,6 +185,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 +195,8 @@ 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-review:v1 severity=medium kind=missing_returns
+    ///      "The method returns Task<User?>, but the <returns> description only says 'A task representing the asynchronous operation' without mentioning the User? result type." -->
     public Task<User?> GetByEmail(string email)
         => throw new LoginServicesException("Not implemented");
 
@@ -196,6 +206,8 @@ 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-review:v1 severity=low kind=missing_returns
+    ///      "The <returns> description 'A task representing the asynchronous operation' omits the User? type that the Task would contain, as declared in the method signature Task<User?>." -->
     public Task<User?> GetByUsername(string username)
         => throw new LoginServicesException("Not implemented");
 
@@ -204,6 +216,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 +228,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 +253,7 @@ 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:v1 sig=d2bafd5 body=4af15eb -->
     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
+    ///      "Summary describes retrieving a list of authorities and mapping LDAP groups to authorities, but the method actually constructs a User object with UserName, first name, and last name from LDAP attributes." -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_returns
+    ///      "Returns description states 'The existing or newly created user with updated authorities', but the method always creates a new User with name information and never deals with authorities or existing users." -->
     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)
 
     {