Add XML doc comments for Microsoft.Net.Http.Headers (#28415)

* Enable missing doc comments to appear as warnings when building locally.
* Update nullability bug that I noticed in RangeConditionHeaderValue

Author: pranavkm

Directory.Build.props

@@ -100,10 +100,11 @@
 
   <!-- Warnings and errors -->
   <PropertyGroup>
+    <!-- Ensure API docs are available. -->
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
+
     <!-- For local builds, don't make missing XML docs a fatal build error, but still surface so we have visibility into undocumented APIs. -->
     <WarningsNotAsErrors Condition=" '$(ContinuousIntegrationBuild)' != 'true' ">$(WarningsNotAsErrors);CS1591</WarningsNotAsErrors>
-    <!-- For CI builds, ensure API docs are available. -->
-    <NoWarn Condition=" '$(ContinuousIntegrationBuild)' == 'true' ">$(NoWarn.Replace('1591', ''))</NoWarn>
 
     <!-- xUnit1004 = warns about skipped tests. Make this a non-fatal build warning. -->
     <WarningsNotAsErrors>$(WarningsNotAsErrors);xUnit1004</WarningsNotAsErrors>

src/Http/Headers/src/CacheControlHeaderValue.cs

@@ -11,19 +11,69 @@
 
 namespace Microsoft.Net.Http.Headers
 {
+    /// <summary>
+    /// Represents the <c>Cache-Control</c> HTTP header.
+    /// </summary>
     public class CacheControlHeaderValue
     {
+        /// <summary>
+        /// A constant for the <c>public</c> cache-control directive.
+        /// </summary>
         public static readonly string PublicString = "public";
+
+        /// <summary>
+        /// A constant for the <c>private</c> cache-control directive.
+        /// </summary>
         public static readonly string PrivateString = "private";
+
+        /// <summary>
+        /// A constant for the <c>max-age</c> cache-control directive.
+        /// </summary>
         public static readonly string MaxAgeString = "max-age";
+
+        /// <summary>
+        /// A constant for the <c>s-maxage</c> cache-control directive.
+        /// </summary>
         public static readonly string SharedMaxAgeString = "s-maxage";
+
+        /// <summary>
+        /// A constant for the <c>no-cache</c> cache-control directive.
+        /// </summary>
         public static readonly string NoCacheString = "no-cache";
+
+        /// <summary>
+        /// A constant for the <c>no-store</c> cache-control directive.
+        /// </summary>
         public static readonly string NoStoreString = "no-store";
+
+        /// <summary>
+        /// A constant for the <c>max-stale</c> cache-control directive.
+        /// </summary>
         public static readonly string MaxStaleString = "max-stale";
+
+        /// <summary>
+        /// A constant for the <c>min-fresh</c> cache-control directive.
+        /// </summary>
         public static readonly string MinFreshString = "min-fresh";
+
+        /// <summary>
+        /// A constant for the <c>no-transform</c> cache-control directive.
+        /// </summary>
         public static readonly string NoTransformString = "no-transform";
+
+        /// <summary>
+        /// A constant for the <c>only-if-cached</c> cache-control directive.
+        /// </summary>
         public static readonly string OnlyIfCachedString = "only-if-cached";
+
+        /// <summary>
+        /// A constant for the <c>must-revalidate</c> cache-control directive.
+        /// </summary>
         public static readonly string MustRevalidateString = "must-revalidate";
+
+        /// <summary>
+        /// A constant for the <c>proxy-revalidate</c> cache-control directive.
+        /// </summary>
         public static readonly string ProxyRevalidateString = "proxy-revalidate";
 
         // The Cache-Control header is special: It is a header supporting a list of values, but we represent the list
@@ -53,17 +103,31 @@ private static readonly HttpHeaderParser<CacheControlHeaderValue> Parser
         private bool _proxyRevalidate;
         private IList<NameValueHeaderValue>? _extensions;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CacheControlHeaderValue"/>.
+        /// </summary>
         public CacheControlHeaderValue()
         {
             // This type is unique in that there is no single required parameter.
         }
 
+        /// <summary>
+        /// Gets or sets a value for the <c>no-cache</c> directive.
+        /// <para>
+        /// Configuring no-cache indicates that the client must re-validate cached responses with the original server
+        /// before using it.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.1.4</remarks>
         public bool NoCache
         {
             get { return _noCache; }
             set { _noCache = value; }
         }
 
+        /// <summary>
+        /// Gets a collection of field names in the "no-cache" directive in a cache-control header field on an HTTP response.
+        /// </summary>
         public ICollection<StringSegment> NoCacheHeaders
         {
             get
@@ -76,66 +140,140 @@ public ICollection<StringSegment> NoCacheHeaders
             }
         }
 
+        /// <summary>
+        /// Gets or sets a value for the <c>no-store</c> directive.
+        /// <para>
+        /// Configuring no-store indicates that the response may not be stored in any cache.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.1.5</remarks>
         public bool NoStore
         {
             get { return _noStore; }
             set { _noStore = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value for the <c>max-age</c> directive.
+        /// <para>
+        /// max-age specifies the maximum amount of time the response is considered fresh.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.1.1</remarks>
         public TimeSpan? MaxAge
         {
             get { return _maxAge; }
             set { _maxAge = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value for the <c>s-maxage</c> directive.
+        /// <para>
+        /// Overrides <see cref="MaxAge">max-age</see>, but only for shared caches (such as proxies).
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.2.9</remarks>
         public TimeSpan? SharedMaxAge
         {
             get { return _sharedMaxAge; }
             set { _sharedMaxAge = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value that determines if the <c>max-stale</c> is included.
+        /// <para>
+        /// <c>max-stale</c> that the client will accept stale responses. The maximum tolerance for staleness
+        /// is specified by <see cref="MaxStaleLimit"/>.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.1.2</remarks>
         public bool MaxStale
         {
             get { return _maxStale; }
             set { _maxStale = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value for the <c>max-stale</c> directive.
+        /// <para>
+        /// Indicates the maximum duration an HTTP client is willing to accept a response that has exceeded its expiration time.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.1.2</remarks>
         public TimeSpan? MaxStaleLimit
         {
             get { return _maxStaleLimit; }
             set { _maxStaleLimit = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value for the <c>min-fresh</c> directive.
+        /// <para>
+        /// Indicates the freshness lifetime that an HTTP client is willing to accept a response.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.1.3</remarks>
         public TimeSpan? MinFresh
         {
             get { return _minFresh; }
             set { _minFresh = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value for the <c>no-transform</c> request directive.
+        /// <para>
+        /// Forbids intermediate caches or proxies from editing the response payload.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.1.6</remarks>
         public bool NoTransform
         {
             get { return _noTransform; }
             set { _noTransform = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value for the <c>only-if-cached</c> request directive.
+        /// <para>
+        /// Indicates that the client only wishes to obtain a stored response
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.1.7</remarks>
         public bool OnlyIfCached
         {
             get { return _onlyIfCached; }
             set { _onlyIfCached = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value that determines if the <c>public</c> response directive is included.
+        /// <para>
+        /// Indicates that the response may be stored by any cache.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.2.5</remarks>
         public bool Public
         {
             get { return _public; }
             set { _public = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value that determines if the <c>private</c> response directive is included.
+        /// <para>
+        /// Indicates that the response may not be stored by a shared cache.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.2.6</remarks>
         public bool Private
         {
             get { return _private; }
             set { _private = value; }
         }
 
+        /// <summary>
+        /// Gets a collection of field names in the "private" directive in a cache-control header field on an HTTP response.
+        /// </summary>
         public ICollection<StringSegment> PrivateHeaders
         {
             get
@@ -148,18 +286,35 @@ public ICollection<StringSegment> PrivateHeaders
             }
         }
 
+        /// <summary>
+        /// Gets or sets a value that determines if the <c>must-revalidate</c> response directive is included.
+        /// <para>
+        /// Indicates that caches must revalidate the use of stale caches with the origin server before their use.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.2.1</remarks>
         public bool MustRevalidate
         {
             get { return _mustRevalidate; }
             set { _mustRevalidate = value; }
         }
 
+        /// <summary>
+        /// Gets or sets a value that determines if the <c>proxy-validate</c> response directive is included.
+        /// <para>
+        /// Indicates that shared caches must revalidate the use of stale caches with the origin server before their use.
+        /// </para>
+        /// </summary>
+        /// <remarks>See https://tools.ietf.org/html/rfc7234#section-5.2.2.1</remarks>
         public bool ProxyRevalidate
         {
             get { return _proxyRevalidate; }
             set { _proxyRevalidate = value; }
         }
 
+        /// <summary>
+        /// Gets cache-extension tokens, each with an optional assigned value.
+        /// </summary>
         public IList<NameValueHeaderValue> Extensions
         {
             get
@@ -172,6 +327,7 @@ public IList<NameValueHeaderValue> Extensions
             }
         }
 
+        /// <inheritdoc />
         public override string ToString()
         {
             var sb = new StringBuilder();
@@ -241,6 +397,7 @@ public override string ToString()
             return sb.ToString();
         }
 
+        /// <inheritdoc />
         public override bool Equals(object? obj)
         {
             var other = obj as CacheControlHeaderValue;
@@ -280,6 +437,7 @@ public override bool Equals(object? obj)
             return true;
         }
 
+        /// <inheritdoc />
         public override int GetHashCode()
         {
             // Use a different bit for bool fields: bool.GetHashCode() will return 0 (false) or 1 (true). So we would
@@ -324,6 +482,11 @@ public override int GetHashCode()
             return result;
         }
 
+        /// <summary>
+        /// Parses <paramref name="input"/> as a <see cref="CacheControlHeaderValue"/> value.
+        /// </summary>
+        /// <param name="input">The values to parse.</param>
+        /// <returns>The parsed values.</returns>
         public static CacheControlHeaderValue Parse(StringSegment input)
         {
             var index = 0;
@@ -336,6 +499,12 @@ public static CacheControlHeaderValue Parse(StringSegment input)
             return result;
         }
 
+        /// <summary>
+        /// Attempts to parse the specified <paramref name="input"/> as a <see cref="CacheControlHeaderValue"/>.
+        /// </summary>
+        /// <param name="input">The value to parse.</param>
+        /// <param name="parsedValue">The parsed value.</param>
+        /// <returns><see langword="true"/> if input is a valid <see cref="SetCookieHeaderValue"/>, otherwise <see langword="false"/>.</returns>
         public static bool TryParse(StringSegment input, [NotNullWhen(true)] out CacheControlHeaderValue? parsedValue)
         {
             var index = 0;