Merge pull request #1750 from unoplatform/dev/lubl/auth-xmldocs

chore(docs): Documenting auth apis

src/Uno.Extensions.Authentication.MSAL/HostBuilderExtensions.cs

@@ -1,8 +1,26 @@
 
 namespace Uno.Extensions;
 
+/// <summary>
+/// Provides extension methods for MSAL authentication to use with <see cref="IAuthenticationBuilder"/>.
+/// </summary>
 public static class HostBuilderExtensions
 {
+	/// <summary>
+	/// Adds MSAL authentication to the specified <see cref="IAuthenticationBuilder"/>.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IAuthenticationBuilder"/> to add MSAL authentication to.
+	/// </param>
+	/// <param name="configure">
+	/// A delegate which can be used to configure the MSAL authentication provider that will be built. Optional.
+	/// </param>
+	/// <param name="name">
+	/// The name of the authentication provider. This optional parameter defaults to "Msal".
+	/// </param>
+	/// <returns>
+	/// The <see cref="IAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IAuthenticationBuilder AddMsal(
 		this IAuthenticationBuilder builder,
 		Action<IMsalAuthenticationBuilder>? configure = default,
@@ -29,7 +47,8 @@ public static IAuthenticationBuilder AddMsal(
 			.AddAuthentication<MsalAuthenticationProvider, MsalAuthenticationSettings>(
 				name,
 				authBuilder.Settings,
-				(provider, settings) => {
+				(provider, settings) =>
+				{
 					provider = provider with { Name = name, Settings = settings };
 					provider.Build();
 					return provider;

src/Uno.Extensions.Authentication.MSAL/IMsalAuthenticationBuilder.cs

@@ -1,5 +1,8 @@
 namespace Uno.Extensions.Authentication.MSAL;
 
+/// <summary>
+/// Implemented by classes that are builders for the MSAL authentication provider feature.
+/// </summary>
 public interface IMsalAuthenticationBuilder : IBuilder
 {
 }

src/Uno.Extensions.Authentication.MSAL/MsalAuthenticationBuilderExtensions.cs

@@ -1,7 +1,22 @@
 namespace Uno.Extensions.Authentication;
 
+/// <summary>
+/// Provides MSAL-related extension methods for <see cref="IMsalAuthenticationBuilder"/>.
+/// </summary>
 public static class MsalAuthenticationBuilderExtensions
 {
+	/// <summary>
+	/// Configures the MSAL authentication feature to use a public client application builder.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IMsalAuthenticationBuilder"/> to configure.
+	/// </param>
+	/// <param name="build">
+	/// A delegate which can be used to create the public client application builder and configure MsalAuthenticationSettings to use it.
+	/// </param>
+	/// <returns>
+	/// The <see cref="IMsalAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IMsalAuthenticationBuilder Builder(
 		this IMsalAuthenticationBuilder builder,
 		Action<PublicClientApplicationBuilder> build
@@ -18,6 +33,18 @@ Action<PublicClientApplicationBuilder> build
 		return builder;
 	}
 
+	/// <summary>
+	/// Configures the MSAL authentication feature to use an incremental builder for StorageCreationProperties objects.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IMsalAuthenticationBuilder"/> to configure.
+	/// </param>
+	/// <param name="store">
+	/// A delegate which can be used to create the StorageCreationPropertiesBuilder and configure MsalAuthenticationSettings to use it.
+	/// </param>
+	/// <returns>
+	/// The <see cref="IMsalAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IMsalAuthenticationBuilder Storage(
 		this IMsalAuthenticationBuilder builder,
 		Action<StorageCreationPropertiesBuilder> store
@@ -34,6 +61,18 @@ Action<StorageCreationPropertiesBuilder> store
 		return builder;
 	}
 
+	/// <summary>
+	/// Configures the MSAL authentication feature to be built with the specified scopes for authentication.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IMsalAuthenticationBuilder"/> to configure.
+	/// </param>
+	/// <param name="scopes">
+	/// The MSAL scopes to use for authentication.
+	/// </param>
+	/// <returns>
+	/// The <see cref="IMsalAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IMsalAuthenticationBuilder Scopes(
 		this IMsalAuthenticationBuilder builder,
 		string[] scopes
@@ -50,6 +89,16 @@ string[] scopes
 		return builder;
 	}
 
+	/// <summary>
+	/// Configures a public client application builder to create the MSAL authentication 
+	/// feature to use the redirect Uri provided by WebAuthenticationBroker.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="PublicClientApplicationBuilder"/> to configure.
+	/// </param>
+	/// <returns>
+	/// The <see cref="PublicClientApplicationBuilder"/> that was passed in.
+	/// </returns>
 	[MethodImpl(MethodImplOptions.NoInlining)]
 	public static PublicClientApplicationBuilder WithWebRedirectUri(this PublicClientApplicationBuilder builder)
 	{

src/Uno.Extensions.Authentication.Oidc/HostBuilderExtensions.cs

@@ -1,7 +1,25 @@
 namespace Uno.Extensions;
 
+/// <summary>
+/// Provides extension methods for OIDC authentication to use with <see cref="IAuthenticationBuilder"/>.
+/// </summary>
 public static class HostBuilderExtensions
 {
+	/// <summary>
+	/// Adds OIDC authentication to the specified <see cref="IAuthenticationBuilder"/>.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IAuthenticationBuilder"/> to add OIDC authentication to.
+	/// </param>
+	/// <param name="configure">
+	/// A delegate which can be used to configure the OIDC authentication provider that will be built. Optional.
+	/// </param>
+	/// <param name="name">
+	/// The name of the authentication provider. This optional parameter defaults to "Oidc".
+	/// </param>
+	/// <returns>
+	/// The <see cref="IAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IAuthenticationBuilder AddOidc(
 		this IAuthenticationBuilder builder,
 		Action<IOidcAuthenticationBuilder>? configure = default,
@@ -32,7 +50,8 @@ public static IAuthenticationBuilder AddOidc(
 			.AddAuthentication<OidcAuthenticationProvider, OidcAuthenticationSettings>(
 				name,
 				authBuilder.Settings,
-				(provider, settings) => {
+				(provider, settings) =>
+				{
 					provider = provider with { Name = name, Settings = settings };
 					provider.Build();
 					return provider;

src/Uno.Extensions.Authentication.Oidc/IOidcAuthenticationBuilder.cs

@@ -1,5 +1,8 @@
 namespace Uno.Extensions.Authentication.Oidc;
 
+/// <summary>
+/// Implemented by classes that are builders for the OIDC authentication provider feature.
+/// </summary>
 public interface IOidcAuthenticationBuilder : IBuilder
 {
 }

src/Uno.Extensions.Authentication.Oidc/OidcAuthenticationBuilderExtensions.cs

@@ -1,32 +1,107 @@
 namespace Uno.Extensions.Authentication;
 
+/// <summary>
+/// Provides OIDC-related extension methods for <see cref="IOidcAuthenticationBuilder"/>.
+/// </summary>
 public static class OidcAuthenticationBuilderExtensions
 {
+	/// <summary>
+	/// Configures the OIDC authentication feature to be built with the specified authority.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IOidcAuthenticationBuilder"/> to configure.
+	/// </param>
+	/// <param name="authority">
+	/// The authority to use for OIDC authentication.
+	/// </param>
+	/// <returns>
+	/// The <see cref="IOidcAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IOidcAuthenticationBuilder Authority(
 		this IOidcAuthenticationBuilder builder,
 		string authority)
 		=> builder.ChangeOption(options => options.Authority = authority);
 
+	/// <summary>
+	/// Configures the OIDC authentication feature to be built with the specified client ID.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IOidcAuthenticationBuilder"/> to configure.
+	/// </param>
+	/// <param name="clientId">
+	/// The client ID to use for OIDC authentication.
+	/// </param>
+	/// <returns>
+	/// The <see cref="IOidcAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IOidcAuthenticationBuilder ClientId(
 		this IOidcAuthenticationBuilder builder,
 		string clientId)
 		=> builder.ChangeOption(options => options.ClientId = clientId);
 
+	/// <summary>
+	/// Configures the OIDC authentication feature to be built with the specified client secret.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IOidcAuthenticationBuilder"/> to configure.
+	/// </param>
+	/// <param name="clientSecret">
+	/// The client secret to use for OIDC authentication.
+	/// </param>
+	/// <returns>
+	/// The <see cref="IOidcAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IOidcAuthenticationBuilder ClientSecret(
 		this IOidcAuthenticationBuilder builder,
 		string clientSecret)
 		=> builder.ChangeOption(options => options.ClientSecret = clientSecret);
 
+	/// <summary>
+	/// Configures the OIDC authentication feature to be built with the specified scope.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IOidcAuthenticationBuilder"/> to configure.
+	/// </param>
+	/// <param name="scope">
+	/// The scope to use for OIDC authentication.
+	/// </param>
+	/// <returns>
+	/// The <see cref="IOidcAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IOidcAuthenticationBuilder Scope(
 	this IOidcAuthenticationBuilder builder,
 	string scope)
 	=> builder.ChangeOption(options => options.Scope = scope);
 
+	/// <summary>
+	/// Configures the OIDC authentication feature to be built with the specified redirect URI.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IOidcAuthenticationBuilder"/> to configure.
+	/// </param>
+	/// <param name="redirectUri">
+	/// The redirect URI to use for OIDC authentication.
+	/// </param>
+	/// <returns>
+	/// The <see cref="IOidcAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IOidcAuthenticationBuilder RedirectUri(
 	this IOidcAuthenticationBuilder builder,
 	string redirectUri)
 	=> builder.ChangeOption(options => options.RedirectUri = redirectUri);
 
+	/// <summary>
+	/// Configures the OIDC authentication feature to be built with the specified post-logout redirect URI.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IOidcAuthenticationBuilder"/> to configure.
+	/// </param>
+	/// <param name="postLogoutRedirectUri">
+	/// The post-logout redirect URI to use for OIDC authentication.
+	/// </param>
+	/// <returns>
+	/// The <see cref="IOidcAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IOidcAuthenticationBuilder PostLogoutRedirectUri(
 	this IOidcAuthenticationBuilder builder,
 	string postLogoutRedirectUri)

src/Uno.Extensions.Authentication.UI/HostBuilderExtensions.cs

@@ -1,7 +1,25 @@
 namespace Uno.Extensions;
 
+/// <summary>
+/// Provides extension methods for web authentication to use with <see cref="IAuthenticationBuilder"/>.
+/// </summary>
 public static class HostBuilderExtensions
 {
+	/// <summary>
+	/// Adds web authentication to the specified <see cref="IAuthenticationBuilder"/>.
+	/// </summary>
+	/// <param name="builder">
+	/// The <see cref="IAuthenticationBuilder"/> to add web authentication to.
+	/// </param>
+	/// <param name="configure">
+	/// A delegate which can be used to configure the web authentication provider that will be built. Optional.
+	/// </param>
+	/// <param name="name">
+	/// The name of the authentication provider. This optional parameter defaults to "Web".
+	/// </param>
+	/// <returns>
+	/// The <see cref="IAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IAuthenticationBuilder AddWeb(
 		this IAuthenticationBuilder builder,
 		Action<IWebAuthenticationBuilder>? configure = default,
@@ -34,6 +52,24 @@ public static IAuthenticationBuilder AddWeb(
 				(provider, settings) => provider with { Name = name, Settings = settings });
 	}
 
+	/// <summary>
+	/// Adds web authentication to the specified <see cref="IAuthenticationBuilder"/>.
+	/// </summary>
+	/// <typeparam name="TService">
+	/// A type of service that will be used by the web authentication provider.
+	/// </typeparam>
+	/// <param name="builder">
+	/// The <see cref="IAuthenticationBuilder"/> to add web authentication to.
+	/// </param>
+	/// <param name="configure">
+	/// A delegate which can be used to configure the web authentication provider that will be built. Optional.
+	/// </param>
+	/// <param name="name">
+	/// The name of the authentication provider. This optional parameter defaults to "Web".
+	/// </param>
+	/// <returns>
+	/// The <see cref="IAuthenticationBuilder"/> that was passed in.
+	/// </returns>
 	public static IAuthenticationBuilder AddWeb<TService>(
 		this IAuthenticationBuilder builder,
 		Action<IWebAuthenticationBuilder<TService>>? configure = default,

src/Uno.Extensions.Authentication.UI/Web/IWebAuthenticationBuilder.cs

@@ -1,9 +1,18 @@
 namespace Uno.Extensions.Authentication.Web;
 
+/// <summary>
+/// Implemented by classes that are builders for the web authentication provider feature.
+/// </summary>
 public interface IWebAuthenticationBuilder : IBuilder
 {
 }
 
+/// <summary>
+/// Implemented by classes that are builders for the web authentication provider feature.
+/// </summary>
+/// <typeparam name="TService">
+/// A service type that is used by the web authentication provider.
+/// </typeparam>
 public interface IWebAuthenticationBuilder<TService> : IWebAuthenticationBuilder
 {
 }