Fix nearly all CS1591 (#40106)

* Fix nearly all CS1591

Fixes #27538

src/Razor/Razor/src/Microsoft.AspNetCore.Razor.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Summary>Razor is a markup syntax for adding server-side logic to web pages. This package contains runtime components for rendering Razor pages and implementing tag helpers.</Summary>
@@ -12,7 +12,6 @@ Microsoft.AspNetCore.Razor.TagHelpers.ITagHelper</Description>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>$(PackageTags);taghelper;taghelpers</PackageTags>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <IsPackable>false</IsPackable>
 
     <!-- Required to implement an HtmlEncoder -->

src/Razor/Razor/src/TagHelpers/HtmlAttributeValueStyle.cs

@@ -1,12 +1,30 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
 namespace Microsoft.AspNetCore.Razor.TagHelpers;
 
+/// <summary>
+/// Determines how an HTML attribute value appears in markup.
+/// </summary>
 public enum HtmlAttributeValueStyle
 {
+    /// <summary>
+    /// An attribute value that appears in double quotes.
+    /// </summary>
     DoubleQuotes,
+
+    /// <summary>
+    /// An attribute value that appears in single quotes.
+    /// </summary>
     SingleQuotes,
+
+    /// <summary>
+    /// An attribute value that appears without quotes.
+    /// </summary>
     NoQuotes,
+
+    /// <summary>
+    /// A minimized attribute value.
+    /// </summary>
     Minimized,
 }

src/Razor/Razor/src/TagHelpers/HtmlTargetElementAttribute.cs

@@ -9,6 +9,9 @@ namespace Microsoft.AspNetCore.Razor.TagHelpers;
 [AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = false)]
 public sealed class HtmlTargetElementAttribute : Attribute
 {
+    /// <summary>
+    /// The value for a tag helper that targets all HTML elements.
+    /// </summary>
     public const string ElementCatchAllTarget = "*";
 
     /// <summary>

src/Razor/Razor/src/TagHelpers/NullHtmlEncoder.cs

@@ -60,6 +60,7 @@ public sealed class NullHtmlEncoder : HtmlEncoder
         output.Write(value, startIndex, characterCount);
     }
 
+    /// <inheritdoc />
     public override void Encode(TextWriter output, string value, int startIndex, int characterCount)
     {
         if (output == null)

src/Razor/Razor/src/TagHelpers/TagHelperOutput.cs

@@ -394,6 +394,7 @@ public class TagHelperOutput : IHtmlContentContainer
         Attributes.Clear();
     }
 
+    /// <inheritdoc />
     public void WriteTo(TextWriter writer, HtmlEncoder encoder)
     {
         if (writer == null)

src/Servers/Connections.Abstractions/src/FileHandleType.cs

@@ -8,7 +8,18 @@ namespace Microsoft.AspNetCore.Connections;
 /// </summary>
 public enum FileHandleType
 {
+    /// <summary>
+    /// This API is unused and no longer supported.
+    /// </summary>
     Auto,
+
+    /// <summary>
+    /// This API is unused and no longer supported.
+    /// </summary>
     Tcp,
+
+    /// <summary>
+    /// This API is unused and no longer supported.
+    /// </summary>
     Pipe
 }

src/Servers/Connections.Abstractions/src/Microsoft.AspNetCore.Connections.Abstractions.csproj

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

src/Servers/Connections.Abstractions/src/TransferFormat.cs

@@ -11,6 +11,13 @@ namespace Microsoft.AspNetCore.Connections;
 [Flags]
 public enum TransferFormat
 {
+    /// <summary>
+    /// A binary transport format.
+    /// </summary>
     Binary = 0x01,
+
+    /// <summary>
+    /// A text transport format.
+    /// </summary>
     Text = 0x02
 }

src/Servers/Connections.Abstractions/src/UriEndPoint.cs

@@ -25,5 +25,6 @@ public class UriEndPoint : EndPoint
     /// </summary>
     public Uri Uri { get; }
 
+    /// <inheritdoc/>
     public override string ToString() => Uri.ToString();
 }

src/Servers/Kestrel/Core/src/BadHttpRequestException.cs

@@ -28,6 +28,9 @@ public sealed class BadHttpRequestException : Microsoft.AspNetCore.Http.BadHttpR
         }
     }
 
+    /// <summary>
+    /// Gets the HTTP status code for this exception.
+    /// </summary>
     public new int StatusCode { get => base.StatusCode; }
 
     internal StringValues AllowedHeader { get; }

src/Servers/Kestrel/Core/src/HttpProtocols.cs

@@ -9,10 +9,33 @@ namespace Microsoft.AspNetCore.Server.Kestrel.Core;
 [Flags]
 public enum HttpProtocols
 {
+    /// <summary>
+    /// No HTTP protocol version was specified.
+    /// </summary>
     None = 0x0,
+
+    /// <summary>
+    /// The HTTP/1.0 protocol version.
+    /// </summary>
     Http1 = 0x1,
+
+    /// <summary>
+    /// The HTTP/2.0 protocol version.
+    /// </summary>
     Http2 = 0x2,
+
+    /// <summary>
+    /// The <see cref="Http1"/> and <see cref="Http2"/> protocol versions.
+    /// </summary>
     Http1AndHttp2 = Http1 | Http2,
+
+    /// <summary>
+    /// The HTTP/3.0 protocol version.
+    /// </summary>
     Http3 = 0x4,
+
+    /// <summary>
+    /// The <see cref="Http1"/>, <see cref="Http2"/>, and <see cref="Http3"/> protocol versions.
+    /// </summary>
     Http1AndHttp2AndHttp3 = Http1 | Http2 | Http3
 }

src/Servers/Kestrel/Core/src/Internal/Http/HttpMethod.cs

@@ -3,19 +3,75 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http;
 
+/// <summary>
+/// This API supports framework infrastructure and is not intended to be used
+/// directly from application code.
+/// </summary>
 public enum HttpMethod : byte
 {
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Get,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Put,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Delete,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Post,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Head,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Trace,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Patch,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Connect,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Options,
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Custom,
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     None = byte.MaxValue,
 }

src/Servers/Kestrel/Core/src/Internal/Http/HttpParser.cs

@@ -11,14 +11,28 @@ namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http;
 
 using BadHttpRequestException = Microsoft.AspNetCore.Http.BadHttpRequestException;
 
+/// <summary>
+/// This API supports framework infrastructure and is not intended to be used
+/// directly from application code.
+/// </summary>
+/// <typeparam name="TRequestHandler">This API supports framework infrastructure and is not intended to be used
+/// directly from application code.</typeparam>
 public class HttpParser<TRequestHandler> : IHttpParser<TRequestHandler> where TRequestHandler : IHttpHeadersHandler, IHttpRequestLineHandler
 {
     private readonly bool _showErrorDetails;
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public HttpParser() : this(showErrorDetails: true)
     {
     }
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public HttpParser(bool showErrorDetails)
     {
         _showErrorDetails = showErrorDetails;
@@ -34,6 +48,10 @@ public class HttpParser<TRequestHandler> : IHttpParser<TRequestHandler> where TR
     private const byte BytePercentage = (byte)'%';
     private const int MinTlsRequestSize = 1; // We need at least 1 byte to check for a proper TLS request line
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public bool ParseRequestLine(TRequestHandler handler, ref SequenceReader<byte> reader)
     {
         if (reader.TryReadTo(out ReadOnlySpan<byte> requestLine, ByteLF, advancePastDelimiter: true))
@@ -137,6 +155,10 @@ public class HttpParser<TRequestHandler> : IHttpParser<TRequestHandler> where TR
         handler.OnStartLine(versionAndMethod, path, startLine);
     }
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public bool ParseHeaders(TRequestHandler handler, ref SequenceReader<byte> reader)
     {
         while (!reader.End)

src/Servers/Kestrel/Core/src/Internal/Http/HttpScheme.cs

@@ -1,11 +1,29 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http;
 
+/// <summary>
+/// This API supports framework infrastructure and is not intended to be used
+/// directly from application code.
+/// </summary>
 public enum HttpScheme
 {
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Unknown = -1,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Http = 0,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Https = 1
 }

src/Servers/Kestrel/Core/src/Internal/Http/HttpVersion.cs

@@ -3,11 +3,39 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http;
 
+/// <summary>
+/// This API supports framework infrastructure and is not intended to be used
+/// directly from application code.
+/// </summary>
 public enum HttpVersion : sbyte
 {
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Unknown = -1,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Http10 = 0,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Http11 = 1,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Http2 = 2,
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     Http3 = 3
 }

src/Servers/Kestrel/Core/src/Internal/Http/IHttpHeadersHandler.cs

@@ -1,12 +1,35 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http;
 
+/// <summary>
+/// This API supports framework infrastructure and is not intended to be used
+/// directly from application code.
+/// </summary>
 public interface IHttpHeadersHandler
 {
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     void OnStaticIndexedHeader(int index);
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     void OnStaticIndexedHeader(int index, ReadOnlySpan<byte> value);
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     void OnHeader(ReadOnlySpan<byte> name, ReadOnlySpan<byte> value);
+
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     void OnHeadersComplete(bool endStream);
 }

src/Servers/Kestrel/Core/src/Internal/Http/IHttpRequestLineHandler.cs

@@ -5,38 +5,74 @@ using System.Runtime.CompilerServices;
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http;
 
+/// <summary>
+/// This API supports framework infrastructure and is not intended to be used
+/// directly from application code.
+/// </summary>
 public interface IHttpRequestLineHandler
 {
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     void OnStartLine(
         HttpVersionAndMethod versionAndMethod,
         TargetOffsetPathLength targetPath,
         Span<byte> startLine);
 }
 
+/// <summary>
+/// This API supports framework infrastructure and is not intended to be used
+/// directly from application code.
+/// </summary>
 public struct HttpVersionAndMethod
 {
     private ulong _versionAndMethod;
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public HttpVersionAndMethod(HttpMethod method, int methodEnd)
     {
         _versionAndMethod = ((ulong)(uint)methodEnd << 32) | ((ulong)method << 8);
     }
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public HttpVersion Version
     {
         get => (HttpVersion)(sbyte)(byte)_versionAndMethod;
         set => _versionAndMethod = (_versionAndMethod & ~0xFFul) | (byte)value;
     }
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public HttpMethod Method => (HttpMethod)(byte)(_versionAndMethod >> 8);
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public int MethodEnd => (int)(uint)(_versionAndMethod >> 32);
 }
 
+/// <summary>
+/// This API supports framework infrastructure and is not intended to be used
+/// directly from application code.
+/// </summary>
 public readonly struct TargetOffsetPathLength
 {
     private readonly ulong _targetOffsetPathLength;
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public TargetOffsetPathLength(int offset, int length, bool isEncoded)
     {
@@ -48,6 +84,10 @@ public readonly struct TargetOffsetPathLength
         _targetOffsetPathLength = ((ulong)offset << 32) | (uint)length;
     }
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public int Offset
     {
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -57,6 +97,10 @@ public readonly struct TargetOffsetPathLength
         }
     }
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public int Length
     {
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -72,6 +116,10 @@ public readonly struct TargetOffsetPathLength
         }
     }
 
+    /// <summary>
+    /// This API supports framework infrastructure and is not intended to be used
+    /// directly from application code.
+    /// </summary>
     public bool IsEncoded
     {
         [MethodImpl(MethodImplOptions.AggressiveInlining)]

src/Servers/Kestrel/Core/src/Microsoft.AspNetCore.Server.Kestrel.Core.csproj

@@ -7,7 +7,6 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;kestrel</PackageTags>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
-    <NoWarn>CS1591;$(NoWarn)</NoWarn>
     <IsPackable>false</IsPackable>
     <DefineConstants>$(DefineConstants);KESTREL</DefineConstants>
     <Nullable>enable</Nullable>

src/Servers/Kestrel/Core/src/MinDataRate.cs

@@ -43,6 +43,7 @@ public class MinDataRate
     /// </summary>
     public TimeSpan GracePeriod { get; }
 
+    /// <inheritdoc />
     public override string ToString()
     {
         return $"Bytes per second: {BytesPerSecond}, Grace Period: {GracePeriod}";

src/Servers/Kestrel/Transport.Quic/src/Microsoft.AspNetCore.Server.Kestrel.Transport.Quic.csproj

@@ -7,7 +7,7 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;kestrel</PackageTags>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
-    <NoWarn>CA1416;CS1591;CS0436;$(NoWarn)</NoWarn><!-- Conflicts between internal and public Quic APIs; Platform support warnings. -->
+    <NoWarn>CA1416;CS0436;$(NoWarn)</NoWarn><!-- Conflicts between internal and public Quic APIs; Platform support warnings. -->
     <IsPackable>false</IsPackable>
     <Nullable>enable</Nullable>
   </PropertyGroup>

src/Servers/Kestrel/Transport.Quic/src/WebHostBuilderQuicExtensions.cs

@@ -9,10 +9,15 @@ using Microsoft.Extensions.DependencyInjection;
 namespace Microsoft.AspNetCore.Hosting;
 
 /// <summary>
-/// Quic <see cref="IWebHostBuilder"/> extensions.
+/// <see cref="IWebHostBuilder" /> extension methods to configure the Quic transport to be used by Kestrel.
 /// </summary>
 public static class WebHostBuilderQuicExtensions
 {
+    /// <summary>
+    /// Specify Quic as the transport to be used by Kestrel.
+    /// </summary>
+    /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+    /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
     public static IWebHostBuilder UseQuic(this IWebHostBuilder hostBuilder)
     {
         if (QuicImplementationProviders.Default.IsSupported)
@@ -26,6 +31,12 @@ public static class WebHostBuilderQuicExtensions
         return hostBuilder;
     }
 
+    /// <summary>
+    /// Specify Quic as the transport to be used by Kestrel.
+    /// </summary>
+    /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+    /// <param name="configureOptions">A callback to configure transport options.</param>
+    /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
     public static IWebHostBuilder UseQuic(this IWebHostBuilder hostBuilder, Action<QuicTransportOptions> configureOptions)
     {
         return hostBuilder.UseQuic().ConfigureServices(services =>

src/Servers/Kestrel/Transport.Sockets/src/Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets.csproj

@@ -7,7 +7,6 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;kestrel</PackageTags>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
-    <NoWarn>CS1591;$(NoWarn)</NoWarn>
     <IsPackable>false</IsPackable>
     <Nullable>enable</Nullable>
   </PropertyGroup>

src/Servers/Kestrel/Transport.Sockets/src/SocketTransportFactory.cs

@@ -16,6 +16,11 @@ public sealed class SocketTransportFactory : IConnectionListenerFactory
     private readonly SocketTransportOptions _options;
     private readonly ILoggerFactory _logger;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SocketTransportFactory"/> class.
+    /// </summary>
+    /// <param name="options">The transport options.</param>
+    /// <param name="loggerFactory">The logger factory.</param>
     public SocketTransportFactory(
         IOptions<SocketTransportOptions> options,
         ILoggerFactory loggerFactory)
@@ -34,6 +39,7 @@ public sealed class SocketTransportFactory : IConnectionListenerFactory
         _logger = loggerFactory;
     }
 
+    /// <inheritdoc />
     public ValueTask<IConnectionListener> BindAsync(EndPoint endpoint, CancellationToken cancellationToken = default)
     {
         var transport = new SocketConnectionListener(endpoint, _options, _logger);