Documentation modifications

adas-core.Authentication/UserService.cs

@@ -47,6 +47,25 @@ public class UserService : IUserService
     private readonly ISubscribersService _subscribersService;
     private readonly IClientMessageService _clientMessageService;
     private readonly Lazy<IPermissionService> _permissionService;
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserService"/> class, capturing the supplied authentication, authorization, user data and logging collaborators for use by subsequent operations.
+    /// </summary>
+    /// <param name="loginServices">The collection of <see cref="ILoginService"/> implementations used to enumerate available login methods.</param>
+    /// <param name="configuration">The <see cref="IOptions{AuthSettings}"/> wrapper whose <see cref="AuthSettings.LoginMethods"/> define the supported login methods.</param>
+    /// <param name="validGroups">The <see cref="IOptions{ValidGroupsConfig}"/> wrapper providing the configured valid user groups.</param>
+    /// <param name="usersWhiteList">The <see cref="IOptions{AuthSettings}"/> wrapper whose <see cref="AuthSettings.UsersWhiteListConfig"/> supplies the users white list.</param>
+    /// <param name="jwt">The <see cref="IOptions{AuthSettings}"/> wrapper whose <see cref="AuthSettings.JwtConfig"/> supplies the JWT configuration.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> used to access the current HTTP context.</param>
+    /// <param name="userRepository">The <see cref="IUserRepository"/> used to read and persist user data.</param>
+    /// <param name="authorityService">The <see cref="IAuthorityService"/> used to perform authority and authorization operations.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record local audit entries.</param>
+    /// <param name="displayService">A <see cref="Lazy{IDisplayService}"/> wrapper providing deferred access to display services.</param>
+    /// <param name="logger">The <see cref="ILogger{UserService}"/> used to log diagnostics for the <see cref="UserService"/>.</param>
+    /// <param name="subscribersService">The <see cref="ISubscribersService"/> used to manage subscribers.</param>
+    /// <param name="clientMessageService">The <see cref="IClientMessageService"/> used to send messages to clients.</param>
+    /// <param name="permissionService">A <see cref="Lazy{IPermissionService}"/> wrapper providing deferred access to permission checks.</param>
+    /// <exception cref="System.Exception">Thrown when the JWT configuration provided by <paramref name="jwt"/> is not configured.</exception>
+    /// <!-- aidoc:v1 sig=8c3130e body=79f6643 -->
     public UserService(
         IEnumerable<ILoginService> loginServices,
         IOptions<AuthSettings> configuration,
@@ -150,6 +169,13 @@ public class UserService : IUserService
             }
         }
 
+    /// <summary>
+    /// Retrieves a <see cref="User"/> based on the username extracted from the provided <paramref name="jwtToken"/>.
+    /// Returns <see langword="null"/> when the token is null or the user cannot be found, clears the retrieved user's password before returning, and lazily loads authorization data from the authority service when it is not already populated.
+    /// </summary>
+    /// <param name="jwtToken">The <see cref="JwtSecurityToken"/> containing the user identity claims, or <see langword="null"/> to indicate no token was supplied.</param>
+    /// <returns>A <see cref="Task{User}"/> that resolves to the matching <see cref="User"/> with its password cleared and authorization loaded if required, or <see langword="null"/> when the token is missing or no user matches the extracted username.</returns>
+    /// <!-- aidoc:v1 sig=29f6fec body=a7970c3 -->
     public async Task<User?> GetUserByToken(JwtSecurityToken? jwtToken)
     {
         User? user = null;