Add more doc comments (#28910)

* Add more doc comments

* DataProtection
* WebUtilities
* JSInterop

* Apply suggestions from code review

Co-authored-by: Chris Ross <[email protected]>
Co-authored-by: James Newton-King <[email protected]>

Co-authored-by: Chris Ross <[email protected]>
Co-authored-by: James Newton-King <[email protected]>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/AuthenticatedEncryptorFactory.cs

@@ -22,15 +22,19 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption
     {
         private readonly ILoggerFactory _loggerFactory;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="AuthenticatedEncryptorFactory"/>.
+        /// </summary>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory"/>.</param>
         public AuthenticatedEncryptorFactory(ILoggerFactory loggerFactory)
         {
             _loggerFactory = loggerFactory;
         }
 
+        /// <inheritdoc />
         public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key)
         {
-            var descriptor = key.Descriptor as AuthenticatedEncryptorDescriptor;
-            if (descriptor == null)
+            if (key.Descriptor is not AuthenticatedEncryptorDescriptor descriptor)
             {
                 return null;
             }

src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngCbcAuthenticatedEncryptorFactory.cs

@@ -23,15 +23,19 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption
     {
         private readonly ILogger _logger;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CngCbcAuthenticatedEncryptorFactory"/>.
+        /// </summary>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory"/>.</param>
         public CngCbcAuthenticatedEncryptorFactory(ILoggerFactory loggerFactory)
         {
             _logger = loggerFactory.CreateLogger<CngCbcAuthenticatedEncryptorFactory>();
         }
 
+        /// <inheritdoc />
         public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key)
         {
-            var descriptor = key.Descriptor as CngCbcAuthenticatedEncryptorDescriptor;
-            if (descriptor == null)
+            if (key.Descriptor is not CngCbcAuthenticatedEncryptorDescriptor descriptor)
             {
                 return null;
             }

src/DataProtection/DataProtection/src/AuthenticatedEncryption/CngGcmAuthenticatedEncryptorFactory.cs

@@ -23,11 +23,16 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption
     {
         private readonly ILogger _logger;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CngCbcAuthenticatedEncryptorFactory"/>.
+        /// </summary>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory"/>.</param>
         public CngGcmAuthenticatedEncryptorFactory(ILoggerFactory loggerFactory)
         {
             _logger = loggerFactory.CreateLogger<CngGcmAuthenticatedEncryptorFactory>();
         }
 
+        /// <inheritdoc />
         public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key)
         {
             var descriptor = key.Descriptor as CngGcmAuthenticatedEncryptorDescriptor;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AlgorithmConfiguration.cs

@@ -1,10 +1,13 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
 
 namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel
 {
+    /// <summary>
+    /// A factory for producing <see cref="IAuthenticatedEncryptorDescriptor"/>.
+    /// </summary>
     public abstract class AlgorithmConfiguration
     {
         internal const int KDK_SIZE_IN_BYTES = 512 / 8;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorConfiguration.cs

@@ -30,6 +30,7 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
         /// </remarks>
         public ValidationAlgorithm ValidationAlgorithm { get; set; } = ValidationAlgorithm.HMACSHA256;
 
+        /// <inheritdoc />
         public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor()
         {
             var internalConfiguration = (IInternalAlgorithmConfiguration)this;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/AuthenticatedEncryptorDescriptor.cs

@@ -12,6 +12,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
     /// </summary>
     public sealed class AuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="AuthenticatedEncryptorDescriptor"/>.
+        /// </summary>
+        /// <param name="configuration">The <see cref="AuthenticatedEncryptorDescriptor"/>.</param>
+        /// <param name="masterKey">The master key.</param>
         public AuthenticatedEncryptorDescriptor(AuthenticatedEncryptorConfiguration configuration, ISecret masterKey)
         {
             if (configuration == null)
@@ -32,6 +37,7 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
 
         internal AuthenticatedEncryptorConfiguration Configuration { get; }
 
+        /// <inheritdoc/>
         public XmlSerializedDescriptorInfo ExportToXml()
         {
             // <descriptor>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorConfiguration.cs

@@ -73,6 +73,7 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
         [ApplyPolicy]
         public string? HashAlgorithmProvider { get; set; } = null;
 
+        /// <inheritdoc />
         public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor()
         {
             var internalConfiguration = (IInternalAlgorithmConfiguration)this;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngCbcAuthenticatedEncryptorDescriptor.cs

@@ -14,6 +14,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
     [SupportedOSPlatform("windows")]
     public sealed class CngCbcAuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="CngCbcAuthenticatedEncryptorDescriptor"/>.
+        /// </summary>
+        /// <param name="configuration">The <see cref="CngCbcAuthenticatedEncryptorConfiguration"/>.</param>
+        /// <param name="masterKey">The master key.</param>
         public CngCbcAuthenticatedEncryptorDescriptor(CngCbcAuthenticatedEncryptorConfiguration configuration, ISecret masterKey)
         {
             if (configuration == null)
@@ -34,6 +39,7 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
 
         internal CngCbcAuthenticatedEncryptorConfiguration Configuration { get; }
 
+        /// <inheritdoc />
         public XmlSerializedDescriptorInfo ExportToXml()
         {
             // <descriptor>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorConfiguration.cs

@@ -49,6 +49,7 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
         [ApplyPolicy]
         public int EncryptionAlgorithmKeySize { get; set; } = 256;
 
+        /// <inheritdoc />
         public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor()
         {
             var internalConfiguration = (IInternalAlgorithmConfiguration)this;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/CngGcmAuthenticatedEncryptorDescriptor.cs

@@ -14,6 +14,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
     [SupportedOSPlatform("windows")]
     public sealed class CngGcmAuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="CngGcmAuthenticatedEncryptorDescriptor"/>.
+        /// </summary>
+        /// <param name="configuration">The <see cref="CngCbcAuthenticatedEncryptorConfiguration"/>.</param>
+        /// <param name="masterKey">The master key.</param>
         public CngGcmAuthenticatedEncryptorDescriptor(CngGcmAuthenticatedEncryptorConfiguration configuration, ISecret masterKey)
         {
             if (configuration == null)
@@ -34,6 +39,7 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
 
         internal CngGcmAuthenticatedEncryptorConfiguration Configuration { get; }
 
+        /// <inheritdoc />
         public XmlSerializedDescriptorInfo ExportToXml()
         {
             // <descriptor>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorConfiguration.cs

@@ -49,6 +49,7 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
         [ApplyPolicy]
         public Type ValidationAlgorithmType { get; set; } = typeof(HMACSHA256);
 
+        /// <inheritdoc />
         public override IAuthenticatedEncryptorDescriptor CreateNewDescriptor()
         {
             var internalConfiguration = (IInternalAlgorithmConfiguration)this;

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/ManagedAuthenticatedEncryptorDescriptor.cs

@@ -13,6 +13,11 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
     /// </summary>
     public sealed class ManagedAuthenticatedEncryptorDescriptor : IAuthenticatedEncryptorDescriptor
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="ManagedAuthenticatedEncryptorDescriptor"/>.
+        /// </summary>
+        /// <param name="configuration">The <see cref="ManagedAuthenticatedEncryptorConfiguration"/>.</param>
+        /// <param name="masterKey">The master key.</param>
         public ManagedAuthenticatedEncryptorDescriptor(ManagedAuthenticatedEncryptorConfiguration configuration, ISecret masterKey)
         {
             if (configuration == null)
@@ -33,6 +38,7 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.Configurat
 
         internal ManagedAuthenticatedEncryptorConfiguration Configuration { get; }
 
+        /// <inheritdoc />
         public XmlSerializedDescriptorInfo ExportToXml()
         {
             // <descriptor>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ConfigurationModel/XmlExtensions.cs

@@ -6,6 +6,9 @@ using System.Xml.Linq;
 
 namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel
 {
+    /// <summary>
+    /// Data protection extensions for <see cref="XElement"/>.
+    /// </summary>
     public static class XmlExtensions
     {
         internal static bool IsMarkedAsRequiringEncryption(this XElement element)

src/DataProtection/DataProtection/src/AuthenticatedEncryption/IAuthenticatedEncryptorFactory.cs

@@ -6,6 +6,9 @@ using Microsoft.AspNetCore.DataProtection.KeyManagement;
 
 namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption
 {
+    /// <summary>
+    /// A factory to produce <see cref="IAuthenticatedEncryptor"/> instances.
+    /// </summary>
     public interface IAuthenticatedEncryptorFactory
     {
         /// <summary>

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ManagedAuthenticatedEncryptorFactory.cs

@@ -19,15 +19,19 @@ namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption
     {
         private readonly ILogger _logger;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="ManagedAuthenticatedEncryptorFactory"/>.
+        /// </summary>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory"/>.</param>
         public ManagedAuthenticatedEncryptorFactory(ILoggerFactory loggerFactory)
         {
             _logger = loggerFactory.CreateLogger<ManagedAuthenticatedEncryptorFactory>();
         }
 
+        /// <inheritdoc />
         public IAuthenticatedEncryptor? CreateEncryptorInstance(IKey key)
         {
-            var descriptor = key.Descriptor as ManagedAuthenticatedEncryptorDescriptor;
-            if (descriptor == null)
+            if (key.Descriptor is not ManagedAuthenticatedEncryptorDescriptor descriptor)
             {
                 return null;
             }

src/DataProtection/DataProtection/src/DataProtectionUtilityExtensions.cs

@@ -8,6 +8,9 @@ using Microsoft.Extensions.DependencyInjection;
 
 namespace Microsoft.AspNetCore.DataProtection
 {
+    /// <summary>
+    /// Data protection extensions for <see cref="IServiceProvider"/>.
+    /// </summary>
     public static class DataProtectionUtilityExtensions
     {
         /// <summary>

src/DataProtection/DataProtection/src/EphemeralDataProtectionProvider.cs

@@ -62,6 +62,7 @@ namespace Microsoft.AspNetCore.DataProtection
             _dataProtectionProvider = new KeyRingBasedDataProtectionProvider(keyringProvider, loggerFactory);
         }
 
+        /// <inheritdoc />
         public IDataProtector CreateProtector(string purpose)
         {
             if (purpose == null)

src/DataProtection/DataProtection/src/KeyManagement/Internal/ICacheableKeyRingProvider.cs

@@ -11,6 +11,10 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement.Internal
     /// </summary>
     public interface ICacheableKeyRingProvider
     {
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         CacheableKeyRing GetCacheableKeyRing(DateTimeOffset now);
     }
 }

src/DataProtection/DataProtection/src/KeyManagement/Internal/IInternalXmlKeyManager.cs

@@ -13,10 +13,22 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement.Internal
     /// </summary>
     public interface IInternalXmlKeyManager
     {
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         IKey CreateNewKey(Guid keyId, DateTimeOffset creationDate, DateTimeOffset activationDate, DateTimeOffset expirationDate);
 
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         IAuthenticatedEncryptorDescriptor DeserializeDescriptorFromKeyElement(XElement keyElement);
 
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         void RevokeSingleKey(Guid keyId, DateTimeOffset revocationDate, string? reason);
     }
 }

src/DataProtection/DataProtection/src/KeyManagement/Internal/IKeyRingProvider.cs

@@ -9,6 +9,10 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement.Internal
     /// </summary>
     public interface IKeyRingProvider
     {
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         IKeyRing GetCurrentKeyRing();
     }
 }

src/DataProtection/DataProtection/src/KeyManagement/KeyManagementOptions.cs

@@ -20,6 +20,9 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement
         private static readonly TimeSpan _maxServerClockSkew = TimeSpan.FromMinutes(5);
         private TimeSpan _newKeyLifetime = TimeSpan.FromDays(90);
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="KeyManagementOptions"/>.
+        /// </summary>
         public KeyManagementOptions()
         {
         }

src/DataProtection/DataProtection/src/KeyManagement/XmlKeyManager.cs

@@ -136,6 +136,7 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement
 
         internal IXmlRepository KeyRepository { get; }
 
+        /// <inheritdoc />
         public IKey CreateNewKey(DateTimeOffset activationDate, DateTimeOffset expirationDate)
         {
             return _internalKeyManager.CreateNewKey(
@@ -151,6 +152,7 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement
             return dateTime.UtcDateTime.ToString("yyyyMMddTHHmmssFFFFFFFZ", CultureInfo.InvariantCulture);
         }
 
+        /// <inheritdoc/>
         public IReadOnlyCollection<IKey> GetAllKeys()
         {
             var allElements = KeyRepository.GetAllElements();
@@ -245,6 +247,7 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement
             return keyIdToKeyMap.Values.ToList().AsReadOnly();
         }
 
+        /// <inheritdoc/>
         public CancellationToken GetCacheExpirationToken()
         {
             Debug.Assert(_cacheExpirationTokenSource != null, $"{nameof(TriggerAndResetCacheExpirationToken)} must have been called first.");
@@ -316,6 +319,7 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement
             }
         }
 
+        /// <inheritdoc/>
         public void RevokeAllKeys(DateTimeOffset revocationDate, string? reason = null)
         {
             // <revocation version="1">
@@ -341,6 +345,7 @@ namespace Microsoft.AspNetCore.DataProtection.KeyManagement
             TriggerAndResetCacheExpirationToken();
         }
 
+        /// <inheritdoc/>
         public void RevokeKey(Guid keyId, string? reason = null)
         {
             _internalKeyManager.RevokeSingleKey(

src/DataProtection/DataProtection/src/Microsoft.AspNetCore.DataProtection.csproj

@@ -1,11 +1,10 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>ASP.NET Core logic to protect and unprotect data, similar to DPAPI.</Description>
     <TargetFrameworks>$(DefaultNetFxTargetFramework);netstandard2.0;$(DefaultNetCoreTargetFramework)</TargetFrameworks>
     <TargetFrameworks Condition="'$(DotNetBuildFromSource)' == 'true'">$(DefaultNetCoreTargetFramework)</TargetFrameworks>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;dataprotection</PackageTags>

src/DataProtection/DataProtection/src/Repositories/FileSystemXmlRepository.cs

@@ -62,6 +62,7 @@ namespace Microsoft.AspNetCore.DataProtection.Repositories
         /// </summary>
         public DirectoryInfo Directory { get; }
 
+        /// <inheritdoc/>
         public virtual IReadOnlyCollection<XElement> GetAllElements()
         {
             // forces complete enumeration
@@ -105,6 +106,7 @@ namespace Microsoft.AspNetCore.DataProtection.Repositories
             }
         }
 
+        /// <inheritdoc/>
         public virtual void StoreElement(XElement element, string friendlyName)
         {
             if (element == null)

src/DataProtection/DataProtection/src/Repositories/RegistryXmlRepository.cs

@@ -54,6 +54,7 @@ namespace Microsoft.AspNetCore.DataProtection.Repositories
         /// </summary>
         public RegistryKey RegistryKey { get; }
 
+        /// <inheritdoc/>
         public virtual IReadOnlyCollection<XElement> GetAllElements()
         {
             // forces complete enumeration
@@ -133,6 +134,7 @@ namespace Microsoft.AspNetCore.DataProtection.Repositories
             return (!string.IsNullOrEmpty(data)) ? XElement.Parse(data) : null;
         }
 
+        /// <inheritdoc/>
         public virtual void StoreElement(XElement element, string friendlyName)
         {
             if (element == null)

src/Http/WebUtilities/src/Base64UrlTextEncoder.cs

@@ -1,8 +1,11 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 namespace Microsoft.AspNetCore.WebUtilities
 {
+    /// <summary>
+    /// Encodes and decodes using base64 url encoding.
+    /// </summary>
     public static class Base64UrlTextEncoder
     {
         /// <summary>

src/Http/WebUtilities/src/FileBufferingReadStream.cs

@@ -45,6 +45,13 @@ namespace Microsoft.AspNetCore.WebUtilities
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FileBufferingReadStream" />.
+        /// </summary>
+        /// <param name="inner">The wrapping <see cref="Stream" />.</param>
+        /// <param name="memoryThreshold">The maximum size to buffer in memory.</param>
+        /// <param name="bufferLimit">The maximum size that will be buffered before this <see cref="Stream"/> throws.</param>
+        /// <param name="tempFileDirectoryAccessor">Provides the temporary directory to which files are buffered to.</param>
         public FileBufferingReadStream(
             Stream inner,
             int memoryThreshold,
@@ -54,6 +61,14 @@ namespace Microsoft.AspNetCore.WebUtilities
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FileBufferingReadStream" />.
+        /// </summary>
+        /// <param name="inner">The wrapping <see cref="Stream" />.</param>
+        /// <param name="memoryThreshold">The maximum size to buffer in memory.</param>
+        /// <param name="bufferLimit">The maximum size that will be buffered before this <see cref="Stream"/> throws.</param>
+        /// <param name="tempFileDirectoryAccessor">Provides the temporary directory to which files are buffered to.</param>
+        /// <param name="bytePool">The <see cref="ArrayPool{T}"/> to use.</param>
         public FileBufferingReadStream(
             Stream inner,
             int memoryThreshold,
@@ -89,6 +104,13 @@ namespace Microsoft.AspNetCore.WebUtilities
             _tempFileDirectoryAccessor = tempFileDirectoryAccessor;
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FileBufferingReadStream" />.
+        /// </summary>
+        /// <param name="inner">The wrapping <see cref="Stream" />.</param>
+        /// <param name="memoryThreshold">The maximum size to buffer in memory.</param>
+        /// <param name="bufferLimit">The maximum size that will be buffered before this <see cref="Stream"/> throws.</param>
+        /// <param name="tempFileDirectory">The temporary directory to which files are buffered to.</param>
         public FileBufferingReadStream(
             Stream inner,
             int memoryThreshold,
@@ -98,6 +120,14 @@ namespace Microsoft.AspNetCore.WebUtilities
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FileBufferingReadStream" />.
+        /// </summary>
+        /// <param name="inner">The wrapping <see cref="Stream" />.</param>
+        /// <param name="memoryThreshold">The maximum size to buffer in memory.</param>
+        /// <param name="bufferLimit">The maximum size that will be buffered before this <see cref="Stream"/> throws.</param>
+        /// <param name="tempFileDirectory">The temporary directory to which files are buffered to.</param>
+        /// <param name="bytePool">The <see cref="ArrayPool{T}"/> to use.</param>
         public FileBufferingReadStream(
             Stream inner,
             int memoryThreshold,
@@ -133,36 +163,47 @@ namespace Microsoft.AspNetCore.WebUtilities
             _tempFileDirectory = tempFileDirectory;
         }
 
+        /// <summary>
+        /// Gets a value that determines if the contents are buffered entirely in memory.
+        /// </summary>
         public bool InMemory
         {
             get { return _inMemory; }
         }
 
+        /// <summary>
+        /// Gets a value that determines where the contents are buffered on disk.
+        /// </summary>
         public string? TempFileName
         {
             get { return _tempFileName; }
         }
 
+        /// <inheritdoc/>
         public override bool CanRead
         {
             get { return true; }
         }
 
+        /// <inheritdoc/>
         public override bool CanSeek
         {
             get { return true; }
         }
 
+        /// <inheritdoc/>
         public override bool CanWrite
         {
             get { return false; }
         }
 
+        /// <inheritdoc/>
         public override long Length
         {
             get { return _buffer.Length; }
         }
 
+        /// <inheritdoc/>
         public override long Position
         {
             get { return _buffer.Position; }
@@ -174,6 +215,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <inheritdoc/>
         public override long Seek(long offset, SeekOrigin origin)
         {
             ThrowIfDisposed();
@@ -209,6 +251,7 @@ namespace Microsoft.AspNetCore.WebUtilities
                 FileOptions.Asynchronous | FileOptions.DeleteOnClose | FileOptions.SequentialScan);
         }
 
+        /// <inheritdoc/>
         public override int Read(Span<byte> buffer)
         {
             ThrowIfDisposed();
@@ -271,16 +314,19 @@ namespace Microsoft.AspNetCore.WebUtilities
             return read;
         }
 
+        /// <inheritdoc/>
         public override int Read(byte[] buffer, int offset, int count)
         {
             return Read(buffer.AsSpan(offset, count));
         }
 
+        /// <inheritdoc/>
         public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
         {
             return ReadAsync(buffer.AsMemory(offset, count), cancellationToken).AsTask();
         }
 
+        /// <inheritdoc/>
         [SuppressMessage("ApiDesign", "RS0027:Public API with optional parameter(s) should have the most parameters amongst its public overloads.", Justification = "Required to maintain compatibility")]
         public override async ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
         {
@@ -343,26 +389,31 @@ namespace Microsoft.AspNetCore.WebUtilities
             return read;
         }
 
+        /// <inheritdoc/>
         public override void Write(byte[] buffer, int offset, int count)
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public override void SetLength(long value)
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public override void Flush()
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public override Task CopyToAsync(Stream destination, int bufferSize, CancellationToken cancellationToken)
         {
             // Set a minimum buffer size of 4K since the base Stream implementation has weird behavior when the stream is
@@ -401,6 +452,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             return CopyToAsyncImpl();
         }
 
+        /// <inheritdoc/>
         protected override void Dispose(bool disposing)
         {
             if (!_disposed)
@@ -418,6 +470,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <inheritdoc/>
         public async override ValueTask DisposeAsync()
         {
             if (!_disposed)

src/Http/WebUtilities/src/FileBufferingWriteStream.cs

@@ -200,6 +200,12 @@ namespace Microsoft.AspNetCore.WebUtilities
             await PagedByteBuffer.MoveToAsync(destination, cancellationToken);
         }
 
+        /// <summary>
+        /// Drains buffered content to <paramref name="destination"/>.
+        /// </summary>
+        /// <param name="destination">The <see cref="PipeWriter" /> to drain buffered contents to.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken" />.</param>
+        /// <returns>A <see cref="Task" /> that represents the asynchronous drain operation.</returns>
         [SuppressMessage("ApiDesign", "RS0026:Do not add multiple public overloads with optional parameters", Justification = "Required to maintain compatibility")]
         public async Task DrainBufferAsync(PipeWriter destination, CancellationToken cancellationToken = default)
         {

src/Http/WebUtilities/src/FormPipeReader.cs

@@ -40,11 +40,20 @@ namespace Microsoft.AspNetCore.WebUtilities
         private readonly PipeReader _pipeReader;
         private readonly Encoding _encoding;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FormPipeReader"/>.
+        /// </summary>
+        /// <param name="pipeReader">The <see cref="PipeReader"/> to read from.</param>
         public FormPipeReader(PipeReader pipeReader)
             : this(pipeReader, Encoding.UTF8)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FormPipeReader"/>.
+        /// </summary>
+        /// <param name="pipeReader">The <see cref="PipeReader"/> to read from.</param>
+        /// <param name="encoding">The <see cref="Encoding"/>.</param>
         public FormPipeReader(PipeReader pipeReader, Encoding encoding)
         {
 #pragma warning disable CS0618, SYSLIB0001 // Type or member is obsolete

src/Http/WebUtilities/src/FormReader.cs

@@ -18,8 +18,19 @@ namespace Microsoft.AspNetCore.WebUtilities
     /// </summary>
     public class FormReader : IDisposable
     {
+        /// <summary>
+        /// Gets the default value for <see cref="ValueCountLimit"/>.
+        /// </summary>
         public const int DefaultValueCountLimit = 1024;
+
+        /// <summary>
+        /// Gets the default value for <see cref="KeyLengthLimit"/>.
+        /// </summary>
         public const int DefaultKeyLengthLimit = 1024 * 2;
+
+        /// <summary>
+        /// Gets the default value for <see cref="ValueLengthLimit" />.
+        /// </summary>
         public const int DefaultValueLengthLimit = 1024 * 1024 * 4;
 
         private const int _rentedCharPoolLength = 8192;
@@ -34,11 +45,20 @@ namespace Microsoft.AspNetCore.WebUtilities
         private bool _endOfStream;
         private bool _disposed;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FormReader"/>.
+        /// </summary>
+        /// <param name="data">The data to read.</param>
         public FormReader(string data)
             : this(data, ArrayPool<char>.Shared)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FormReader"/>.
+        /// </summary>
+        /// <param name="data">The data to read.</param>
+        /// <param name="charPool">The <see cref="ArrayPool{T}"/> to use.</param>
         public FormReader(string data, ArrayPool<char> charPool)
         {
             if (data == null)
@@ -51,16 +71,31 @@ namespace Microsoft.AspNetCore.WebUtilities
             _reader = new StringReader(data);
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FormReader"/>.
+        /// </summary>
+        /// <param name="stream">The <see cref="Stream"/> to read. Assumes a <c>utf-8</c> encoded stream.</param>
         public FormReader(Stream stream)
             : this(stream, Encoding.UTF8, ArrayPool<char>.Shared)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FormReader"/>.
+        /// </summary>
+        /// <param name="stream">The <see cref="Stream"/> to read.</param>
+        /// <param name="encoding">The character encoding to use.</param>
         public FormReader(Stream stream, Encoding encoding)
             : this(stream, encoding, ArrayPool<char>.Shared)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="FormReader"/>.
+        /// </summary>
+        /// <param name="stream">The <see cref="Stream"/> to read.</param>
+        /// <param name="encoding">The character encoding to use.</param>
+        /// <param name="charPool">The <see cref="ArrayPool{T}"/> to use.</param>
         public FormReader(Stream stream, Encoding encoding, ArrayPool<char> charPool)
         {
             if (stream == null)
@@ -302,6 +337,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <inheritdoc />
         public void Dispose()
         {
             if (!_disposed)

src/Http/WebUtilities/src/HttpRequestStreamReader.cs

@@ -12,6 +12,9 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.WebUtilities
 {
+    /// <summary>
+    /// A <see cref="TextReader"/> to read the HTTP request stream.
+    /// </summary>
     public class HttpRequestStreamReader : TextReader
     {
         private const int DefaultBufferSize = 1024;
@@ -36,16 +39,35 @@ namespace Microsoft.AspNetCore.WebUtilities
         private bool _isBlocked;
         private bool _disposed;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="HttpRequestStreamReader"/>.
+        /// </summary>
+        /// <param name="stream">The HTTP request <see cref="Stream"/>.</param>
+        /// <param name="encoding">The character encoding to use.</param>
         public HttpRequestStreamReader(Stream stream, Encoding encoding)
             : this(stream, encoding, DefaultBufferSize, ArrayPool<byte>.Shared, ArrayPool<char>.Shared)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="HttpRequestStreamReader"/>.
+        /// </summary>
+        /// <param name="stream">The HTTP request <see cref="Stream"/>.</param>
+        /// <param name="encoding">The character encoding to use.</param>
+        /// <param name="bufferSize">The minimum buffer size.</param>
         public HttpRequestStreamReader(Stream stream, Encoding encoding, int bufferSize)
             : this(stream, encoding, bufferSize, ArrayPool<byte>.Shared, ArrayPool<char>.Shared)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="HttpRequestStreamReader"/>.
+        /// </summary>
+        /// <param name="stream">The HTTP request <see cref="Stream"/>.</param>
+        /// <param name="encoding">The character encoding to use.</param>
+        /// <param name="bufferSize">The minimum buffer size.</param>
+        /// <param name="bytePool">The byte array pool to use.</param>
+        /// <param name="charPool">The char array pool to use.</param>
         public HttpRequestStreamReader(
             Stream stream,
             Encoding encoding,
@@ -90,6 +112,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <inheritdoc />
         protected override void Dispose(bool disposing)
         {
             if (disposing && !_disposed)
@@ -103,6 +126,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             base.Dispose(disposing);
         }
 
+        /// <inheritdoc />
         public override int Peek()
         {
             if (_disposed)
@@ -121,6 +145,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             return _charBuffer[_charBufferIndex];
         }
 
+        /// <inheritdoc />
         public override int Read()
         {
             if (_disposed)
@@ -139,6 +164,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             return _charBuffer[_charBufferIndex++];
         }
 
+        /// <inheritdoc />
         public override int Read(char[] buffer, int index, int count)
         {
             if (buffer == null)
@@ -160,6 +186,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             return Read(span);
         }
 
+        /// <inheritdoc />
         public override int Read(Span<char> buffer)
         {
             if (buffer == null)
@@ -213,6 +240,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             return charsRead;
         }
 
+        /// <inheritdoc />
         public override Task<int> ReadAsync(char[] buffer, int index, int count)
         {
             if (buffer == null)
@@ -234,6 +262,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             return ReadAsync(memory).AsTask();
         }
 
+        /// <inheritdoc />
         [SuppressMessage("ApiDesign", "RS0027:Public API with optional parameter(s) should have the most parameters amongst its public overloads.", Justification = "Required to maintain compatibility")]
         public override async ValueTask<int> ReadAsync(Memory<char> buffer, CancellationToken cancellationToken = default)
         {
@@ -330,6 +359,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             return charsRead;
         }
 
+        /// <inheritdoc />
         public override async Task<string?> ReadLineAsync()
         {
             if (_disposed)
@@ -367,6 +397,7 @@ namespace Microsoft.AspNetCore.WebUtilities
         // immediately followed by a line feed. The resulting string does not
         // contain the terminating carriage return and/or line feed. The returned
         // value is null if the end of the input stream has been reached.
+        /// <inheritdoc />
         public override string? ReadLine()
         {
             if (_disposed)
@@ -530,6 +561,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             return _charsRead;
         }
 
+        /// <inheritdoc />
         public async override Task<string> ReadToEndAsync()
         {
             StringBuilder sb = new StringBuilder(_charsRead - _charBufferIndex);

src/Http/WebUtilities/src/HttpResponseStreamWriter.cs

@@ -14,7 +14,7 @@ using System.Threading.Tasks;
 namespace Microsoft.AspNetCore.WebUtilities
 {
     /// <summary>
-    /// Writes to the <see cref="Stream"/> using the supplied <see cref="Encoding"/>.
+    /// Writes to the HTTP response <see cref="Stream"/> using the supplied <see cref="System.Text.Encoding"/>.
     /// It does not write the BOM and also does not close the stream.
     /// </summary>
     public class HttpResponseStreamWriter : TextWriter
@@ -34,16 +34,35 @@ namespace Microsoft.AspNetCore.WebUtilities
         private int _charBufferCount;
         private bool _disposed;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="HttpResponseStreamWriter"/>.
+        /// </summary>
+        /// <param name="stream">The HTTP response <see cref="Stream"/>.</param>
+        /// <param name="encoding">The character encoding to use.</param>
         public HttpResponseStreamWriter(Stream stream, Encoding encoding)
             : this(stream, encoding, DefaultBufferSize, ArrayPool<byte>.Shared, ArrayPool<char>.Shared)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="HttpResponseStreamWriter"/>.
+        /// </summary>
+        /// <param name="stream">The HTTP response <see cref="Stream"/>.</param>
+        /// <param name="encoding">The character encoding to use.</param>
+        /// <param name="bufferSize">The minimum buffer size.</param>
         public HttpResponseStreamWriter(Stream stream, Encoding encoding, int bufferSize)
             : this(stream, encoding, bufferSize, ArrayPool<byte>.Shared, ArrayPool<char>.Shared)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="HttpResponseStreamWriter"/>.
+        /// </summary>
+        /// <param name="stream">The HTTP response <see cref="Stream"/>.</param>
+        /// <param name="encoding">The character encoding to use.</param>
+        /// <param name="bufferSize">The minimum buffer size.</param>
+        /// <param name="bytePool">The byte array pool.</param>
+        /// <param name="charPool">The char array pool.</param>
         public HttpResponseStreamWriter(
             Stream stream,
             Encoding encoding,
@@ -88,8 +107,10 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <inheritdoc/>
         public override Encoding Encoding { get; }
 
+        /// <inheritdoc/>
         public override void Write(char value)
         {
             if (_disposed)
@@ -106,6 +127,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             _charBufferCount++;
         }
 
+        /// <inheritdoc/>
         public override void Write(char[] values, int index, int count)
         {
             if (_disposed)
@@ -129,6 +151,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <inheritdoc/>
         public override void Write(ReadOnlySpan<char> value)
         {
             if (_disposed)
@@ -151,6 +174,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             };
         }
 
+        /// <inheritdoc/>
         public override void Write(string? value)
         {
             if (_disposed)
@@ -176,6 +200,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <inheritdoc/>
         public override void WriteLine(ReadOnlySpan<char> value)
         {
             if (_disposed)
@@ -187,6 +212,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             Write(NewLine);
         }
 
+        /// <inheritdoc/>
         public override Task WriteAsync(char value)
         {
             if (_disposed)
@@ -217,6 +243,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             _charBufferCount++;
         }
 
+        /// <inheritdoc/>
         public override Task WriteAsync(char[] values, int index, int count)
         {
             if (_disposed)
@@ -258,6 +285,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <inheritdoc/>
         public override Task WriteAsync(string? value)
         {
             if (_disposed)
@@ -302,6 +330,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <inheritdoc/>
         [SuppressMessage("ApiDesign", "RS0027:Public API with optional parameter(s) should have the most parameters amongst its public overloads.", Justification = "Required to maintain compatibility")]
         public override Task WriteAsync(ReadOnlyMemory<char> value, CancellationToken cancellationToken = default)
         {
@@ -353,6 +382,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             };
         }
 
+        /// <inheritdoc/>
         public override Task WriteLineAsync(ReadOnlyMemory<char> value, CancellationToken cancellationToken = default)
         {
             if (_disposed)
@@ -393,6 +423,7 @@ namespace Microsoft.AspNetCore.WebUtilities
         // We want to flush the stream when Flush/FlushAsync is explicitly
         // called by the user (example: from a Razor view).
 
+        /// <inheritdoc/>
         public override void Flush()
         {
             if (_disposed)
@@ -403,6 +434,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             FlushInternal(flushEncoder: true);
         }
 
+        /// <inheritdoc/>
         public override Task FlushAsync()
         {
             if (_disposed)
@@ -413,6 +445,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             return FlushInternalAsync(flushEncoder: true);
         }
 
+        /// <inheritdoc/>
         protected override void Dispose(bool disposing)
         {
             if (disposing && !_disposed)
@@ -432,6 +465,7 @@ namespace Microsoft.AspNetCore.WebUtilities
             base.Dispose(disposing);
         }
 
+        /// <inheritdoc/>
         public override async ValueTask DisposeAsync()
         {
             if (!_disposed)

src/Http/WebUtilities/src/KeyValueAccumulator.cs

@@ -7,11 +7,19 @@ using Microsoft.Extensions.Primitives;
 
 namespace Microsoft.AspNetCore.WebUtilities
 {
+    /// <summary>
+    /// This API supports infrastructure and is not intended to be used
+    /// directly from your code. This API may change or be removed in future releases.
+    /// </summary>
     public struct KeyValueAccumulator
     {
         private Dictionary<string, StringValues> _accumulator;
         private Dictionary<string, List<string>> _expandingAccumulator;
 
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         public void Append(string key, string value)
         {
             if (_accumulator == null)
@@ -63,12 +71,28 @@ namespace Microsoft.AspNetCore.WebUtilities
             ValueCount++;
         }
 
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         public bool HasValues => ValueCount > 0;
 
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         public int KeyCount => _accumulator?.Count ?? 0;
 
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         public int ValueCount { get; private set; }
 
+        /// <summary>
+        /// This API supports infrastructure and is not intended to be used
+        /// directly from your code. This API may change or be removed in future releases.
+        /// </summary>
         public Dictionary<string, StringValues> GetResults()
         {
             if (_expandingAccumulator != null)

src/Http/WebUtilities/src/Microsoft.AspNetCore.WebUtilities.csproj

@@ -5,7 +5,6 @@
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <DefineConstants>$(DefineConstants);WebEncoders_In_WebUtilities</DefineConstants>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore</PackageTags>
     <IsPackable>false</IsPackable>

src/Http/WebUtilities/src/MultipartReader.cs

@@ -12,9 +12,19 @@ using Microsoft.Extensions.Primitives;
 namespace Microsoft.AspNetCore.WebUtilities
 {
     // https://www.ietf.org/rfc/rfc2046.txt
+    /// <summary>
+    /// Reads multipart form content from the specified <see cref="Stream"/>.
+    /// </summary>
     public class MultipartReader
     {
+        /// <summary>
+        /// Gets the default value for <see cref="HeadersCountLimit"/>.
+        /// </summary>
         public const int DefaultHeadersCountLimit = 16;
+
+        /// <summary>
+        /// Gets the default value for <see cref="HeadersLengthLimit"/>.
+        /// </summary>
         public const int DefaultHeadersLengthLimit = 1024 * 16;
         private const int DefaultBufferSize = 1024 * 4;
 
@@ -22,11 +32,22 @@ namespace Microsoft.AspNetCore.WebUtilities
         private readonly MultipartBoundary _boundary;
         private MultipartReaderStream _currentStream;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="MultipartReader"/>.
+        /// </summary>
+        /// <param name="boundary">The multipart boundary.</param>
+        /// <param name="stream">The <see cref="Stream"/> containing multipart data.</param>
         public MultipartReader(string boundary, Stream stream)
             : this(boundary, stream, DefaultBufferSize)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="MultipartReader"/>.
+        /// </summary>
+        /// <param name="boundary">The multipart boundary.</param>
+        /// <param name="stream">The <see cref="Stream"/> containing multipart data.</param>
+        /// <param name="bufferSize">The minimum buffer size to use.</param>
         public MultipartReader(string boundary, Stream stream, int bufferSize)
         {
             if (boundary == null)
@@ -65,6 +86,12 @@ namespace Microsoft.AspNetCore.WebUtilities
         /// </summary>
         public long? BodyLengthLimit { get; set; }
 
+        /// <summary>
+        /// Reads the next <see cref="MultipartSection"/>.
+        /// </summary>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests.
+        /// The default value is <see cref="CancellationToken.None"/>.</param>
+        /// <returns></returns>
         public async Task<MultipartSection?> ReadNextSectionAsync(CancellationToken cancellationToken = new CancellationToken())
         {
             // Drain the prior section.

src/Http/WebUtilities/src/MultipartSection.cs

@@ -8,8 +8,14 @@ using Microsoft.Net.Http.Headers;
 
 namespace Microsoft.AspNetCore.WebUtilities
 {
+    /// <summary>
+    /// A multipart section read by <see cref="MultipartReader"/>.
+    /// </summary>
     public class MultipartSection
     {
+        /// <summary>
+        /// Gets the value of the <c>Content-Type</c> header.
+        /// </summary>
         public string? ContentType
         {
             get
@@ -22,6 +28,9 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <summary>
+        /// Gets the value of the <c>Content-Disposition</c> header.
+        /// </summary>
         public string? ContentDisposition
         {
             get
@@ -34,6 +43,9 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
 
+        /// <summary>
+        /// Gets or sets the multipart header collection.
+        /// </summary>
         public Dictionary<string, StringValues>? Headers { get; set; }
 
         /// <summary>

src/Http/WebUtilities/src/ReasonPhrases.cs

@@ -5,10 +5,14 @@ using System.Collections.Generic;
 
 namespace Microsoft.AspNetCore.WebUtilities
 {
+    /// <summary>
+    /// Provides access to HTTP status code reason phrases as listed in 
+    /// http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml.
+    /// </summary>
     public static class ReasonPhrases
     {
         // Status Codes listed at http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
-        private static IDictionary<int, string> Phrases = new Dictionary<int, string>()
+        private static readonly Dictionary<int, string> Phrases = new()
         {
             { 100, "Continue" },
             { 101, "Switching Protocols" },
@@ -78,6 +82,11 @@ namespace Microsoft.AspNetCore.WebUtilities
             { 511, "Network Authentication Required" },
         };
 
+        /// <summary>
+        /// Gets the reason phrase for the specified status code. 
+        /// </summary>
+        /// <param name="statusCode">The status code.</param>
+        /// <returns>The reason phrase, or <see cref="string.Empty"/> if the status code is unknown.</returns>
         public static string GetReasonPhrase(int statusCode)
         {
             return Phrases.TryGetValue(statusCode, out var phrase) ? phrase : string.Empty;

src/Http/WebUtilities/src/StreamHelperExtensions.cs

@@ -8,20 +8,53 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.WebUtilities
 {
+    /// <summary>
+    /// HTTP extension methods for <see cref="Stream"/>.
+    /// </summary>
     public static class StreamHelperExtensions
     {
         private const int _maxReadBufferSize = 1024 * 4;
 
+        /// <summary>
+        /// Reads the specified <paramref name="stream"/> to the end.
+        /// <para>
+        /// This API is effective when used in conjunction with buffering. It allows
+        /// a buffered request stream to be synchronously read after it has been completely drained.
+        /// </para>
+        /// </summary>
+        /// <param name="stream">The <see cref="Stream"/> to completely read.</param>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
         public static Task DrainAsync(this Stream stream, CancellationToken cancellationToken)
         {
             return stream.DrainAsync(ArrayPool<byte>.Shared, null, cancellationToken);
         }
 
+        /// <summary>
+        /// Reads the specified <paramref name="stream"/> to the end.
+        /// <para>
+        /// This API is effective when used in conjunction with buffering. It allows
+        /// a buffered request stream to be synchronously read after it has been completely drained.
+        /// </para>
+        /// </summary>
+        /// <param name="stream">The <see cref="Stream"/> to completely read.</param>
+        /// <param name="limit">The maximum number of bytes to read. Throws if the <see cref="Stream"/> is larger than this limit.</param>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
         public static Task DrainAsync(this Stream stream, long? limit, CancellationToken cancellationToken)
         {
             return stream.DrainAsync(ArrayPool<byte>.Shared, limit, cancellationToken);
         }
 
+        /// <summary>
+        /// Reads the specified <paramref name="stream"/> to the end.
+        /// <para>
+        /// This API is effective when used in conjunction with buffering. It allows
+        /// a buffered request stream to be synchronously read after it has been completely drained.
+        /// </para>
+        /// </summary>
+        /// <param name="stream">The <see cref="Stream"/> to completely read.</param>
+        /// <param name="bytePool">The byte array pool to use.</param>
+        /// <param name="limit">The maximum number of bytes to read. Throws if the <see cref="Stream"/> is larger than this limit.</param>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
         public static async Task DrainAsync(this Stream stream, ArrayPool<byte> bytePool, long? limit, CancellationToken cancellationToken)
         {
             cancellationToken.ThrowIfCancellationRequested();
@@ -48,4 +81,4 @@ namespace Microsoft.AspNetCore.WebUtilities
             }
         }
     }
-}
+}

src/JSInterop/Microsoft.JSInterop/src/JSInProcessObjectReferenceExtensions.cs

@@ -5,6 +5,9 @@ using System;
 
 namespace Microsoft.JSInterop
 {
+    /// <summary>
+    /// Extension methods for <see cref="IJSInProcessObjectReference"/>.
+    /// </summary>
     public static class JSInProcessObjectReferenceExtensions
     {
         /// <summary>

src/JSInterop/Microsoft.JSInterop/src/Microsoft.JSInterop.csproj

@@ -6,7 +6,6 @@
     <PackageTags>javascript;interop</PackageTags>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <Nullable>enable</Nullable>
   </PropertyGroup>
 

src/ObjectPool/src/DefaultObjectPool.cs

@@ -55,6 +55,7 @@ namespace Microsoft.Extensions.ObjectPool
             }
         }
 
+        /// <inheritdoc />
         public override T Get()
         {
             var item = _firstItem;
@@ -80,6 +81,7 @@ namespace Microsoft.Extensions.ObjectPool
         [MethodImpl(MethodImplOptions.NoInlining)]
         private T Create() => _fastPolicy?.Create() ?? _policy.Create();
 
+        /// <inheritdoc />
         public override void Return(T obj)
         {
             if (_isDefaultPolicy || (_fastPolicy?.Return(obj) ?? _policy.Return(obj)))

src/ObjectPool/src/DefaultPooledObjectPolicy.cs

@@ -1,19 +1,25 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// Default implementation for <see cref="PooledObjectPolicy{T}"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of object which is being pooled.</typeparam>
     public class DefaultPooledObjectPolicy<T> : PooledObjectPolicy<T> where T : class, new()
     {
+        /// <inheritdoc />
         public override T Create()
         {
             return new T();
         }
 
-        // DefaultObjectPool<T> doesn't call 'Return' for the default policy.
-        // So take care adding any logic to this method, as it might require changes elsewhere.
+        /// <inheritdoc />
         public override bool Return(T obj)
         {
+            // DefaultObjectPool<T> doesn't call 'Return' for the default policy.
+            // So take care adding any logic to this method, as it might require changes elsewhere.
             return true;
         }
     }

src/ObjectPool/src/LeakTrackingObjectPool.cs

@@ -7,11 +7,24 @@ using System.Runtime.CompilerServices;
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// An <see cref="ObjectPool{T}"/> implementation that detects leaks in the use of the object pool.
+    /// <para>
+    /// A leak is produced if an object is leased from the pool but not returned before it is finalized.
+    /// An error is only produced in <c>Debug</c> builds.
+    /// This type is only recommended to be used for diagnostc builds.
+    /// </para>
+    /// </summary>
+    /// <typeparam name="T">The type of object which is being pooled.</typeparam>
     public class LeakTrackingObjectPool<T> : ObjectPool<T> where T : class
     {
         private readonly ConditionalWeakTable<T, Tracker> _trackers = new ConditionalWeakTable<T, Tracker>();
         private readonly ObjectPool<T> _inner;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="LeakTrackingObjectPool{T}"/>.
+        /// </summary>
+        /// <param name="inner">The <see cref="ObjectPool{T}"/> instance to track leaks in.</param>
         public LeakTrackingObjectPool(ObjectPool<T> inner)
         {
             if (inner == null)
@@ -22,6 +35,7 @@ namespace Microsoft.Extensions.ObjectPool
             _inner = inner;
         }
 
+        /// <inheritdoc/>
         public override T Get()
         {
             var value = _inner.Get();
@@ -29,6 +43,7 @@ namespace Microsoft.Extensions.ObjectPool
             return value;
         }
 
+        /// <inheritdoc/>
         public override void Return(T obj)
         {
             if (_trackers.TryGetValue(obj, out var tracker))

src/ObjectPool/src/LeakTrackingObjectPoolProvider.cs

@@ -1,14 +1,22 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// An <see cref="ObjectPoolProvider"/> that produces instances of
+    /// <see cref="LeakTrackingObjectPool{T}"/>.
+    /// </summary>
     public class LeakTrackingObjectPoolProvider : ObjectPoolProvider
     {
         private readonly ObjectPoolProvider _inner;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="LeakTrackingObjectPoolProvider"/>.
+        /// </summary>
+        /// <param name="inner">The <see cref="ObjectPoolProvider"/> to wrap.</param>
         public LeakTrackingObjectPoolProvider(ObjectPoolProvider inner)
         {
             if (inner == null)
@@ -19,6 +27,7 @@ namespace Microsoft.Extensions.ObjectPool
             _inner = inner;
         }
 
+        /// <inheritdoc/>
         public override ObjectPool<T> Create<T>(IPooledObjectPolicy<T> policy)
         {
             var inner = _inner.Create<T>(policy);

src/ObjectPool/src/Microsoft.Extensions.ObjectPool.csproj

@@ -3,7 +3,6 @@
   <PropertyGroup>
     <Description>A simple object pool implementation.</Description>
     <TargetFrameworks>$(DefaultNetFxTargetFramework);netstandard2.0;$(DefaultNetCoreTargetFramework)</TargetFrameworks>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>pooling</PackageTags>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>

src/ObjectPool/src/ObjectPoolProviderExtensions.cs

@@ -1,17 +1,33 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System.Text;
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// Extension methods for <see cref="ObjectPoolProvider"/>.
+    /// </summary>
     public static class ObjectPoolProviderExtensions
     {
+        /// <summary>
+        /// Creates an <see cref="ObjectPool{T}"/> that pools <see cref="StringBuilder"/> instances.
+        /// </summary>
+        /// <param name="provider">The <see cref="ObjectPoolProvider"/>.</param>
+        /// <returns>The <see cref="ObjectPool{T}"/>.</returns>
         public static ObjectPool<StringBuilder> CreateStringBuilderPool(this ObjectPoolProvider provider)
         {
             return provider.Create<StringBuilder>(new StringBuilderPooledObjectPolicy());
         }
 
+        /// <summary>
+        /// Creates an <see cref="ObjectPool{T}"/> that pools <see cref="StringBuilder"/> instances.
+        /// </summary>
+        /// <param name="provider">The <see cref="ObjectPoolProvider"/>.</param>
+        /// <param name="initialCapacity">The initial capacity to initiaize <see cref="StringBuilder"/> instances with.</param>
+        /// <param name="maximumRetainedCapacity">The maximum value for <see cref="StringBuilder.Capacity"/> that is allowed to be
+        /// retained, when an instance is returned.</param>
+        /// <returns>The <see cref="ObjectPool{T}"/>.</returns>
         public static ObjectPool<StringBuilder> CreateStringBuilderPool(
             this ObjectPoolProvider provider,
             int initialCapacity,

src/ObjectPool/src/PooledObjectPolicy.cs

@@ -1,12 +1,18 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// A base type for <see cref="IPooledObjectPolicy{T}"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of object which is being pooled.</typeparam>
     public abstract class PooledObjectPolicy<T> : IPooledObjectPolicy<T> where T : notnull
     {
+        /// <inheritdoc />
         public abstract T Create();
 
+        /// <inheritdoc />
         public abstract bool Return(T obj);
     }
 }

src/ObjectPool/src/StringBuilderPooledObjectPolicy.cs

@@ -1,21 +1,35 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System.Text;
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// A policy for pooling <see cref="StringBuilder"/> instances.
+    /// </summary>
     public class StringBuilderPooledObjectPolicy : PooledObjectPolicy<StringBuilder>
     {
+        /// <summary>
+        /// Gets or sets the initial capacity of pooled <see cref="StringBuilder"/> instances.
+        /// </summary>
+        /// <value>Defaults to <c>100</c>.</value>
         public int InitialCapacity { get; set; } = 100;
 
+        /// <summary>
+        /// Gets or sets the maximum value for <see cref="StringBuilder.Capacity"/> that is allowed to be
+        /// retained, when <see cref="Return(StringBuilder)"/> is invoked.
+        /// </summary>
+        /// <value>Defaults to <c>4096</c>.</value>
         public int MaximumRetainedCapacity { get; set; } = 4 * 1024;
 
+        /// <inheritdoc />
         public override StringBuilder Create()
         {
             return new StringBuilder(InitialCapacity);
         }
 
+        /// <inheritdoc />
         public override bool Return(StringBuilder obj)
         {
             if (obj.Capacity > MaximumRetainedCapacity)