Add API docs to twitter auth (#29473)

Author: HaoK

src/Security/Authentication/Twitter/src/Messages/RequestToken.cs

@@ -18,6 +18,9 @@ public class RequestToken
         /// </summary>
         public string TokenSecret { get; set; }
 
+        /// <summary>
+        /// Gets or sets whether the callback was confirmed.
+        /// </summary>
         public bool CallbackConfirmed { get; set; }
 
         /// <summary>

src/Security/Authentication/Twitter/src/Microsoft.AspNetCore.Authentication.Twitter.csproj

@@ -3,7 +3,6 @@
   <PropertyGroup>
     <Description>ASP.NET Core middleware that enables an application to support Twitter's OAuth 1.0 authentication workflow.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;authentication;security</PackageTags>
   </PropertyGroup>

src/Security/Authentication/Twitter/src/TwitterDefaults.cs

@@ -3,10 +3,19 @@
 
 namespace Microsoft.AspNetCore.Authentication.Twitter
 {
+    /// <summary>
+    /// Default values for the Twitter authentication handler.
+    /// </summary>
     public static class TwitterDefaults
     {
+        /// <summary>
+        /// The default scheme for Twitter authentication. The value is <c>Twitter</c>.
+        /// </summary>
         public const string AuthenticationScheme = "Twitter";
 
+        /// <summary>
+        /// The default display name for Twitter authentication. Defaults to <c>Twitter</c>.
+        /// </summary>
         public static readonly string DisplayName = "Twitter";
 
         // https://developer.twitter.com/en/docs/basics/authentication/api-reference/request_token

src/Security/Authentication/Twitter/src/TwitterExtensions.cs

@@ -9,17 +9,62 @@
 
 namespace Microsoft.Extensions.DependencyInjection
 {
+    /// <summary>
+    /// Extension methods to configure Twitter OAuth authentication.
+    /// </summary>
     public static class TwitterExtensions
     {
+        /// <summary>
+        /// Adds Twitter OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="TwitterDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Facebook authentication allows application users to sign in with their Facebook account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddTwitter(this AuthenticationBuilder builder)
             => builder.AddTwitter(TwitterDefaults.AuthenticationScheme, _ => { });
 
+        /// <summary>
+        /// Adds Twitter OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="TwitterDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Facebook authentication allows application users to sign in with their Facebook account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="TwitterOptions"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddTwitter(this AuthenticationBuilder builder, Action<TwitterOptions> configureOptions)
             => builder.AddTwitter(TwitterDefaults.AuthenticationScheme, configureOptions);
 
+        /// <summary>
+        /// Adds Twitter OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="TwitterDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Facebook authentication allows application users to sign in with their Facebook account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="TwitterOptions"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddTwitter(this AuthenticationBuilder builder, string authenticationScheme, Action<TwitterOptions> configureOptions)
             => builder.AddTwitter(authenticationScheme, TwitterDefaults.DisplayName, configureOptions);
 
+        /// <summary>
+        /// Adds Twitter OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="TwitterDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Facebook authentication allows application users to sign in with their Facebook account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
+        /// <param name="displayName">A display name for the authentication handler.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="TwitterOptions"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddTwitter(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action<TwitterOptions> configureOptions)
         {
             builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IPostConfigureOptions<TwitterOptions>, TwitterPostConfigureOptions>());

src/Security/Authentication/Twitter/src/TwitterHandler.cs

@@ -22,6 +22,9 @@
 
 namespace Microsoft.AspNetCore.Authentication.Twitter
 {
+    /// <summary>
+    /// Authentication handler for Twitter's OAuth based authentication.
+    /// </summary>
     public class TwitterHandler : RemoteAuthenticationHandler<TwitterOptions>
     {
         private static readonly JsonSerializerOptions ErrorSerializerOptions = new JsonSerializerOptions
@@ -41,12 +44,18 @@ public class TwitterHandler : RemoteAuthenticationHandler<TwitterOptions>
             set { base.Events = value; }
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="TwitterHandler"/>.
+        /// </summary>
+        /// <inheritdoc />
         public TwitterHandler(IOptionsMonitor<TwitterOptions> options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock)
             : base(options, logger, encoder, clock)
         { }
 
+        /// <inheritdoc />
         protected override Task<object> CreateEventsAsync() => Task.FromResult<object>(new TwitterEvents());
 
+        /// <inheritdoc />
         protected override async Task<HandleRequestResult> HandleRemoteAuthenticateAsync()
         {
             var query = Request.Query;
@@ -130,6 +139,14 @@ protected override async Task<HandleRequestResult> HandleRemoteAuthenticateAsync
             }
         }
 
+        /// <summary>
+        /// Creates an <see cref="AuthenticationTicket"/> from the specified <paramref name="token"/>.
+        /// </summary>
+        /// <param name="identity">The <see cref="ClaimsIdentity"/>.</param>
+        /// <param name="properties">The <see cref="AuthenticationProperties"/>.</param>
+        /// <param name="token">The <see cref="AccessToken"/>.</param>
+        /// <param name="user">The <see cref="JsonElement"/> for the user.</param>
+        /// <returns>The <see cref="AuthenticationTicket"/>.</returns>
         protected virtual async Task<AuthenticationTicket> CreateTicketAsync(
             ClaimsIdentity identity, AuthenticationProperties properties, AccessToken token, JsonElement user)
         {
@@ -144,6 +161,7 @@ protected virtual async Task<AuthenticationTicket> CreateTicketAsync(
             return new AuthenticationTicket(context.Principal, context.Properties, Scheme.Name);
         }
 
+        /// <inheritdoc />
         protected override async Task HandleChallengeAsync(AuthenticationProperties properties)
         {
             if (string.IsNullOrEmpty(properties.RedirectUri))

src/Security/Authentication/Twitter/src/TwitterPostConfigureOptions.cs

@@ -14,6 +14,10 @@ public class TwitterPostConfigureOptions : IPostConfigureOptions<TwitterOptions>
     {
         private readonly IDataProtectionProvider _dp;
 
+        /// <summary>
+        /// Initializes the <see cref="TwitterPostConfigureOptions"/>.
+        /// </summary>
+        /// <param name="dataProtection">The <see cref="IDataProtectionProvider"/>.</param>
         public TwitterPostConfigureOptions(IDataProtectionProvider dataProtection)
         {
             _dp = dataProtection;