ljrojas91/adas-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(iec62304): [REL-1.0.2] apply curated XML doc review updates

Browse Source
This commit is contained in:
n8n IEC 62304 Bot
2026-07-06 18:42:11 +02:00
parent a67a9f5443
commit 5b4dc2710b
2 changed files with 130 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files
adas-core.LdapLogin/LdapLoginService.cs
+26 -32
View File
@@ -157,25 +157,23 @@ public class LdapLoginService : ILoginService
}
/// <summary>
/// This method is not implemented in the LdapLoginService, as the login process is handled through the Login(string username, string password) method.
/// Authenticates a user using the provided HTTP context. The implementation is not yet provided and the method always throws a <see cref="LoginServicesException"/>.
/// </summary>
/// <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." -->
/// <param name="context">The current <see cref="HttpContext"/> carrying the request data used for authentication.</param>
/// <returns>A <see cref="Task{User}"/> that will resolve to the authenticated user once the method is implemented.</returns>
/// <exception cref="LoginServicesException">Thrown because the login operation has not been implemented.</exception>
/// <!-- aidoc:v1 sig=851dc90 -->
public Task<User> Login(HttpContext context)
=> throw new LoginServicesException("Not implemented");
/// <summary>
/// This method is not implemented in the LdapLoginService, as the authentication process is handled through the Login(string username, string password) method.
/// Authenticates a user with the provided <paramref name="username"/> and <paramref name="password"/>.
/// </summary>
/// <param name="username">The username of the user to authenticate.</param>
/// <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." -->
/// <param name="username">The username of the user attempting to authenticate.</param>
/// <param name="password">The password of the user attempting to authenticate.</param>
/// <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 -->
public Task<User> Authenticate(string username, string password)
=> throw new LoginServicesException("Not implemented");
@@ -190,24 +188,23 @@ public class LdapLoginService : ILoginService
=> throw new LoginServicesException("Not implemented");
/// <summary>
/// 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 <see cref="User"/> matching the supplied email address, or <see langword="null"/> when no user is found.
/// </summary>
/// <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." -->
/// <param name="email">The email address used to look up the <see cref="User"/>.</param>
/// <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 -->
public Task<User?> GetByEmail(string email)
=> throw new LoginServicesException("Not implemented");
/// <summary>
/// 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.
/// Asynchronously retrieves a <see cref="User"/> by the supplied <paramref name="username"/>.
/// The current implementation always throws <see cref="LoginServicesException"/> because the operation is not implemented.
/// </summary>
/// <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?>." -->
/// <param name="username">The username used to look up the <see cref="User"/>.</param>
/// <returns>A <see cref="Task{TResult}"/> that resolves to the matching <see cref="User"/>, or <see langword="null"/> if no user is found.</returns>
/// <exception cref="LoginServicesException">Thrown for every invocation because the operation is not implemented.</exception>
/// <!-- aidoc:v1 sig=5184c30 -->
public Task<User?> GetByUsername(string username)
=> throw new LoginServicesException("Not implemented");
@@ -343,14 +340,11 @@ public class LdapLoginService : ILoginService
/// <summary>
/// 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.
/// Constructs a <see cref="User"/> from the attributes of the supplied <paramref name="ldapEntry"/>, mapping the LDAP username, first name, and last name properties according to the current configuration. The username falls back to an empty string when the configured attribute is missing, and first/last name values are only applied when their corresponding configuration entries are set and the LDAP entry exposes those attributes, with the last name appended to the first name when both are available.
/// </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." -->
/// <param name="ldapEntry">The <see cref="LdapEntry"/> whose attributes are read to populate the <see cref="User"/>.</param>
/// <returns>A <see cref="User"/> populated from the <paramref name="ldapEntry"/> attributes.</returns>
/// <!-- aidoc:v1 sig=947181a body=33ffec8 -->
private User GetUser(LdapEntry ldapEntry)
{