API docs for Components (#26505)

* Turn on doc warnings

* Api ref stuff

* Add api docs

* Api docs

* Missing docs

* Add docs

* Update src/Components/WebAssembly/WebAssembly.Authentication/src/Services/ExpiredTokenException.cs

Co-authored-by: Pranav K <prkrishn@hotmail.com>

Co-authored-by: Pranav K <prkrishn@hotmail.com>

src/Components/Analyzers/src/Microsoft.AspNetCore.Components.Analyzers.csproj

@@ -6,6 +6,7 @@
     <NoPackageAnalysis>true</NoPackageAnalysis>
     <GenerateDocumentationFile>false</GenerateDocumentationFile>
     <Description>Roslyn analyzers for ASP.NET Core Components.</Description>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Components/Authorization/src/AuthorizeRouteView.cs

@@ -30,6 +30,9 @@ namespace Microsoft.AspNetCore.Components.Authorization
         private readonly RenderFragment<AuthenticationState> _renderNotAuthorizedDelegate;
         private readonly RenderFragment _renderAuthorizingDelegate;
 
+        /// <summary>
+        /// Initialize a new instance of a <see cref="AuthorizeRouteView"/>.
+        /// </summary>
         public AuthorizeRouteView()
         {
             // Cache the rendering delegates so that we only construct new closure instances

src/Components/Authorization/src/Microsoft.AspNetCore.Components.Authorization.csproj

@@ -5,6 +5,7 @@
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <Description>Authentication and authorization support for Blazor applications.</Description>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Components/Components/src/Microsoft.AspNetCore.Components.csproj

@@ -6,6 +6,7 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Components/Components/src/RouteView.cs

@@ -35,6 +35,9 @@ namespace Microsoft.AspNetCore.Components
         [Parameter]
         public Type DefaultLayout { get; set; }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="RouteView"/>.
+        /// </summary>
         public RouteView()
         {
             // Cache the delegate instances

src/Components/Components/src/Routing/NavigationContext.cs

@@ -17,8 +17,14 @@ namespace Microsoft.AspNetCore.Components.Routing
             CancellationToken = cancellationToken;
         }
 
+        /// <summary>
+        /// The target path for the navigation.
+        /// </summary>
         public string Path { get; }
 
+        /// <summary>
+        /// The <see cref="CancellationToken"/> to use to cancel navigation.
+        /// </summary>
         public CancellationToken CancellationToken { get; }
     }
 }

src/Components/Forms/src/Microsoft.AspNetCore.Components.Forms.csproj

@@ -6,6 +6,7 @@
     <Description>Forms and validation support for Blazor applications.</Description>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Components/Server/src/Microsoft.AspNetCore.Components.Server.csproj

@@ -6,7 +6,7 @@
     <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
-    <NoWarn>CS0436;$(NoWarn)</NoWarn>
+    <NoWarn>CS0436;$(NoWarn.Replace('1591', ''))</NoWarn>
     <DefineConstants>$(DefineConstants);ENABLE_UNSAFE_MSGPACK;SPAN_BUILTIN;MESSAGEPACK_INTERNAL;COMPONENTS_SERVER</DefineConstants>
     <IsPackable>false</IsPackable>
     <EmbeddedFilesManifestFileName>Microsoft.Extensions.FileProviders.Embedded.Manifest.xml</EmbeddedFilesManifestFileName>

src/Components/Web/src/ElementReferenceExtensions.cs

@@ -7,6 +7,9 @@ using Microsoft.JSInterop;
 
 namespace Microsoft.AspNetCore.Components
 {
+    /// <summary>
+    /// Static class that adds extension methods to <see cref="ElementReference"/>.
+    /// </summary>
     public static class ElementReferenceExtensions
     {
         /// <summary>

src/Components/Web/src/Forms/InputBase.cs

@@ -287,6 +287,7 @@ namespace Microsoft.AspNetCore.Components.Forms
             return newDictionaryCreated;
         }
 
+        /// <inheritdoc/>
         protected virtual void Dispose(bool disposing)
         {
         }

src/Components/Web/src/Forms/InputFile.cs

@@ -41,11 +41,13 @@ namespace Microsoft.AspNetCore.Components.Forms
         [Parameter(CaptureUnmatchedValues = true)]
         public IDictionary<string, object>? AdditionalAttributes { get; set; }
 
+        /// <inheritdoc/>
         protected override void OnInitialized()
         {
             _jsUnmarshalledRuntime = JSRuntime as IJSUnmarshalledRuntime;
         }
 
+        /// <inheritdoc/>
         protected override async Task OnAfterRenderAsync(bool firstRender)
         {
             if (firstRender)
@@ -55,6 +57,7 @@ namespace Microsoft.AspNetCore.Components.Forms
             }
         }
 
+        /// <inheritdoc/>
         protected override void BuildRenderTree(RenderTreeBuilder builder)
         {
             builder.OpenElement(0, "input");

src/Components/Web/src/Forms/ValidationMessage.cs

@@ -80,6 +80,10 @@ namespace Microsoft.AspNetCore.Components.Forms
             }
         }
 
+        /// <summary>
+        /// Called to dispose this instance.
+        /// </summary>
+        /// <param name="disposing"><see langword="true"/> if called within <see cref="IDisposable.Dispose"/>.</param>
         protected virtual void Dispose(bool disposing)
         {
         }

src/Components/Web/src/Forms/ValidationSummary.cs

@@ -92,6 +92,7 @@ namespace Microsoft.AspNetCore.Components.Forms
             }
         }
 
+        /// <inheritdoc/>
         protected virtual void Dispose(bool disposing)
         {
         }

src/Components/Web/src/Microsoft.AspNetCore.Components.Web.csproj

@@ -7,6 +7,7 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <RootNamespace>Microsoft.AspNetCore.Components</RootNamespace>
     <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Components/Web/src/Routing/NavLink.cs

@@ -157,6 +157,7 @@ namespace Microsoft.AspNetCore.Components.Routing
             return false;
         }
 
+        /// <inheritdoc/>
         protected override void BuildRenderTree(RenderTreeBuilder builder)
         {
             builder.OpenElement(0, "a");

src/Components/Web/src/WebElementReferenceContext.cs

@@ -6,10 +6,17 @@ using Microsoft.JSInterop;
 
 namespace Microsoft.AspNetCore.Components
 {
+    /// <summary>
+    /// A <see cref="ElementReferenceContext"/> for a web element.
+    /// </summary>
     public class WebElementReferenceContext : ElementReferenceContext
     {
         internal IJSRuntime JSRuntime { get; }
 
+        /// <summary>
+        /// Initialize a new instance of <see cref="WebElementReferenceContext"/>.
+        /// </summary>
+        /// <param name="jsRuntime">The <see cref="IJSRuntime"/>.</param>
         public WebElementReferenceContext(IJSRuntime jsRuntime)
         {
             JSRuntime = jsRuntime ?? throw new ArgumentNullException(nameof(jsRuntime));

src/Components/WebAssembly/Authentication.Msal/src/Microsoft.Authentication.WebAssembly.Msal.csproj

@@ -6,6 +6,7 @@
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <Description>Authenticate your Blazor webassembly applications with Azure Active Directory and Azure Active Directory B2C</Description>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Components/WebAssembly/DevServer/src/Microsoft.AspNetCore.Components.WebAssembly.DevServer.csproj

@@ -9,6 +9,7 @@
     <StartupObject>Microsoft.AspNetCore.Components.WebAssembly.DevServer.Program</StartupObject>
     <Description>Development server for use when building Blazor applications.</Description>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <!-- Set this to false because assemblies should not reference this assembly directly, (except for tests, of course). -->
     <IsProjectReferenceProvider>false</IsProjectReferenceProvider>
 

src/Components/WebAssembly/JSInterop/src/Microsoft.JSInterop.WebAssembly.csproj

@@ -6,6 +6,7 @@
     <PackageTags>wasm;javascript;interop</PackageTags>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <IsShippingPackage>true</IsShippingPackage>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Components/WebAssembly/JSInterop/src/WebAssemblyJSRuntime.cs

@@ -48,6 +48,7 @@ namespace Microsoft.JSInterop.WebAssembly
             InternalCalls.InvokeJS<object, object, object, string>(out _, ref callInfo, null, null, null);
         }
 
+        /// <inheritdoc />
         protected override void EndInvokeDotNet(DotNetInvocationInfo callInfo, in DotNetInvocationResult dispatchResult)
         {
             // For failures, the common case is to call EndInvokeDotNet with the Exception object.

src/Components/WebAssembly/Sdk/src/Microsoft.NET.Sdk.BlazorWebAssembly.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <Description>MSBuild support for building Blazor WebAssembly apps.</Description>
     <TargetFrameworks>$(DefaultNetCoreTargetFramework);net46</TargetFrameworks>
@@ -9,7 +9,7 @@
     <SdkOutputPath>$(ArtifactsBinDir)Microsoft.NET.Sdk.BlazorWebAssembly\$(Configuration)\sdk-output\</SdkOutputPath>
 
     <!-- Allow assemblies outside of lib in the package -->
-    <NoWarn>$(NoWarn);NU5100</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''));NU5100</NoWarn>
     <!-- Need to build this project in source build -->
     <ExcludeFromSourceBuild>false</ExcludeFromSourceBuild>
 

src/Components/WebAssembly/Server/src/Microsoft.AspNetCore.Components.WebAssembly.Server.csproj

@@ -6,7 +6,7 @@
     <IsShippingPackage>true</IsShippingPackage>
 
     <!-- We're deliberately bundling assemblies as content files. Suppress the warning. -->
-    <NoWarn>$(NoWarn);NU5100</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''));NU5100</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 

src/Components/WebAssembly/Server/src/TargetPickerUi.cs

@@ -14,6 +14,9 @@ using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Components.WebAssembly.Server
 {
+    /// <summary>
+    /// Class for the target picker ui.
+    /// </summary>
     public class TargetPickerUi
     {
         private static readonly JsonSerializerOptions JsonOptions = new JsonSerializerOptions
@@ -26,12 +29,22 @@ namespace Microsoft.AspNetCore.Components.WebAssembly.Server
         private string _browserHost;
         private string _debugProxyUrl;
 
+        /// <summary>
+        /// Initialize a new instance of <see cref="TargetPickerUi"/>.
+        /// </summary>
+        /// <param name="debugProxyUrl">The debug proxy url.</param>
+        /// <param name="devToolsHost">The dev tools host.</param>
         public TargetPickerUi(string debugProxyUrl, string devToolsHost)
         {
             _debugProxyUrl = debugProxyUrl;
             _browserHost = devToolsHost;
         }
 
+        /// <summary>
+        /// Display the ui.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/>.</param>
+        /// <returns>The <see cref="Task"/>.</returns>
         public async Task Display(HttpContext context)
         {
             context.Response.ContentType = "text/html";

src/Components/WebAssembly/WebAssembly.Authentication/src/IRemoteAuthenticationBuilder.cs

@@ -14,6 +14,9 @@ namespace Microsoft.Extensions.DependencyInjection
         where TRemoteAuthenticationState : RemoteAuthenticationState
         where TAccount : RemoteUserAccount
     {
+        /// <summary>
+        /// The <see cref="IServiceCollection"/>.
+        /// </summary>
         IServiceCollection Services { get; }
     }
 }

src/Components/WebAssembly/WebAssembly.Authentication/src/Microsoft.AspNetCore.Components.WebAssembly.Authentication.csproj

@@ -7,6 +7,7 @@
     <Description>Build client-side authentication for single-page applications (SPAs).</Description>
     <IsShippingPackage>true</IsShippingPackage>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Components/WebAssembly/WebAssembly.Authentication/src/Services/AccountClaimsPrincipalFactory.cs

@@ -17,6 +17,10 @@ namespace Microsoft.AspNetCore.Components.WebAssembly.Authentication
         private readonly IAccessTokenProviderAccessor _accessor;
 
 #pragma warning disable PUB0001 // Pubternal type in public API
+        /// <summary>
+        /// Initialize a new instance of <see cref="AccountClaimsPrincipalFactory{TAccount}"/>.
+        /// </summary>
+        /// <param name="accessor"></param>
         public AccountClaimsPrincipalFactory(IAccessTokenProviderAccessor accessor) => _accessor = accessor;
 
         /// <summary>

src/Components/WebAssembly/WebAssembly.Authentication/src/Services/ExpiredTokenException.cs

@@ -17,6 +17,12 @@ namespace Microsoft.AspNetCore.Components.WebAssembly.Authentication
         private readonly NavigationManager _navigation;
         private readonly AccessTokenResult _tokenResult;
 
+        /// <summary>
+        /// Initialize a new instance of <see cref="AccessTokenNotAvailableException"/>.
+        /// </summary>
+        /// <param name="navigation">The <see cref="NavigationManager"/>.</param>
+        /// <param name="tokenResult">The <see cref="AccessTokenResult"/>.</param>
+        /// <param name="scopes">The scopes.</param>
         public AccessTokenNotAvailableException(
             NavigationManager navigation,
             AccessTokenResult tokenResult,
@@ -28,6 +34,9 @@ namespace Microsoft.AspNetCore.Components.WebAssembly.Authentication
             _navigation = navigation;
         }
 
+        /// <summary>
+        /// Navigates to <see cref="AccessTokenResult.RedirectUrl"/> to allow refreshing the access token.
+        /// </summary>
         public void Redirect() => _navigation.NavigateTo(_tokenResult.RedirectUrl);
     }
 }

src/Components/WebAssembly/WebAssembly.Authentication/src/Services/SignOutSessionStateManager.cs

@@ -19,6 +19,10 @@ namespace Microsoft.AspNetCore.Components.WebAssembly.Authentication
             PropertyNameCaseInsensitive = true,
         };
 
+        /// <summary>
+        /// Initialize a new instance of <see cref="SignOutSessionStateManager"/>.
+        /// </summary>
+        /// <param name="jsRuntime">The <see cref="IJSRuntime"/>.</param>
         public SignOutSessionStateManager(IJSRuntime jsRuntime) => _jsRuntime = jsRuntime;
 
         /// <summary>

src/Components/WebAssembly/WebAssembly/src/Hosting/WebAssemblyHostEnvironmentExtensions.cs

@@ -4,6 +4,9 @@ using System.Text;
 
 namespace Microsoft.AspNetCore.Components.WebAssembly.Hosting
 {
+    /// <summary>
+    /// Static class that adds extension methods to <see cref="IWebAssemblyHostEnvironment"/>.
+    /// </summary>
     public static class WebAssemblyHostEnvironmentExtensions
     {
         /// <summary>

src/Components/WebAssembly/WebAssembly/src/Microsoft.AspNetCore.Components.WebAssembly.csproj

@@ -1,10 +1,10 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <Description>Build client-side single-page applications (SPAs) with Blazor running under WebAssembly.</Description>
     <IsShippingPackage>true</IsShippingPackage>
-    <NoWarn>$(NoWarn);BL0006</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''));BL0006</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 

src/Components/WebAssembly/WebAssembly/src/Services/LazyAssemblyLoader.cs

@@ -28,6 +28,10 @@ namespace Microsoft.AspNetCore.Components.WebAssembly.Services
         private readonly IJSRuntime _jsRuntime;
         private readonly HashSet<string> _loadedAssemblyCache;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="LazyAssemblyLoader"/>.
+        /// </summary>
+        /// <param name="jsRuntime">The <see cref="IJSRuntime"/>.</param>
         public LazyAssemblyLoader(IJSRuntime jsRuntime)
         {
             _jsRuntime = jsRuntime;