Update System.Net.WebHeaderCollection docs (#4642)

Author: CarnaViire

xml/System.Net/HttpListenerResponse.xml

@@ -159,7 +159,7 @@
  -or-  
 
  <paramref name="name" /> or <paramref name="value" /> contains invalid characters.</exception>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65,535 characters.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65,535 characters.</exception>
         <altmember cref="T:System.Net.HttpListener" />
         <altmember cref="T:System.Net.HttpListenerContext" />
         <altmember cref="T:System.Net.HttpListenerRequest" />
@@ -283,7 +283,7 @@
  -or-  
 
  <paramref name="name" /> or <paramref name="value" /> contains invalid characters.</exception>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65,535 characters.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65,535 characters.</exception>
         <altmember cref="T:System.Net.HttpListener" />
         <altmember cref="T:System.Net.HttpListenerContext" />
         <altmember cref="T:System.Net.HttpListenerRequest" />

xml/System.Net/WebHeaderCollection.xml

@@ -290,6 +290,11 @@
  [!code-csharp[WebHeaderCollection_Add#1](~/samples/snippets/csharp/VS_Snippets_Remoting/WebHeaderCollection_Add/CS/webheadercollection_add.cs#1)]
  [!code-vb[WebHeaderCollection_Add#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Add/VB/webheadercollection_add.vb#1)]  
   
+> [!NOTE]
+> The length of the *value* portion of `header`, that is, the string after the colon (:), is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
+> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of the *value* portion of `header` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a *value* of any length.
+> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of the *value* portion of `header` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a *value* of any length.
+> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a *value* of any length.
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
@@ -310,7 +315,7 @@
  -or-  
 
  The value part of <paramref name="header" /> contains invalid characters.</exception>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length the string after the colon (:) is greater than 65535.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of the string after the colon (:) is greater than 65535.</exception>
       </Docs>
     </Member>
     <Member MemberName="Add">
@@ -364,9 +369,14 @@
   
  If the specified header is already present, `value` is added to the comma-separated list of values associated with the header.  
   
+> [!NOTE]
+> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
+> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
  ]]></format>
         </remarks>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
         <exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpRequestHeader" />.</exception>
       </Docs>
     </Member>
@@ -421,9 +431,14 @@
   
  If the specified header is already present, `value` is added to the comma-separated list of values associated with the header.  
   
+> [!NOTE]
+> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
+> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
  ]]></format>
         </remarks>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
         <exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpResponseHeader" />.</exception>
       </Docs>
     </Member>
@@ -489,6 +504,11 @@
  [!code-csharp[WebHeaderCollection_Add#1](~/samples/snippets/csharp/VS_Snippets_Remoting/WebHeaderCollection_Add/CS/webheadercollection_add.cs#1)]
  [!code-vb[WebHeaderCollection_Add#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Add/VB/webheadercollection_add.vb#1)]  
   
+> [!NOTE]
+> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
+> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">
@@ -501,7 +521,7 @@
  -or-  
 
  <paramref name="value" /> contains invalid characters.</exception>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
       </Docs>
     </Member>
     <Member MemberName="AddWithoutValidate">
@@ -555,6 +575,11 @@
 ## Remarks  
  The <xref:System.Net.WebHeaderCollection.AddWithoutValidate%2A> method adds a header to the collection without checking whether the header is on the restricted header list.  
   
+> [!NOTE]
+> The length of `headerValue` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
+> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `headerValue` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `headerValue` of any length.
+> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `headerValue` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `headerValue` of any length.
+> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `headerValue` of any length.
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">
@@ -564,7 +589,7 @@
 
  <paramref name="headerValue" /> contains invalid characters.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="headerName" /> is not <see langword="null" /> and the length of <paramref name="headerValue" /> is too long (greater than 65,535 characters).</exception>
+          .NET Framework and .NET Core only: <paramref name="headerName" /> is not <see langword="null" /> and the length of <paramref name="headerValue" /> is too long (greater than 65,535 characters).</exception>
         <block subset="none" type="overrides">
           <para>Use the <see cref="M:System.Net.WebHeaderCollection.AddWithoutValidate(System.String,System.String)" /> method to add headers that are normally exposed through properties.</para>
         </block>
@@ -1453,8 +1478,19 @@
         <param name="header">The response header value.</param>
         <summary>Gets or sets the specified response header.</summary>
         <value>A <see cref="T:System.String" /> instance containing the specified header.</value>
-        <remarks>To be added.</remarks>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+
+> [!NOTE]
+> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
+> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
         <exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpResponseHeader" />.</exception>
       </Docs>
     </Member>
@@ -1837,9 +1873,14 @@
   
  If the header specified in `header` is already present, `value` replaces the existing value.  
   
+> [!NOTE]
+> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
+> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
  ]]></format>
         </remarks>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
         <exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpRequestHeader" />.</exception>
       </Docs>
     </Member>
@@ -1894,9 +1935,14 @@
   
  If the header specified in `header` is already present, `value` replaces the existing value.  
   
+> [!NOTE]
+> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
+> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
  ]]></format>
         </remarks>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
         <exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpResponseHeader" />.</exception>
       </Docs>
     </Member>
@@ -1962,11 +2008,16 @@
  [!code-csharp[WebHeaderCollection_Set#1](~/samples/snippets/csharp/VS_Snippets_Remoting/WebHeaderCollection_Set/CS/webheadercollection_set.cs#1)]
  [!code-vb[WebHeaderCollection_Set#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Set/VB/webheadercollection_set.vb#1)]  
   
+> [!NOTE]
+> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
+> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
+> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="name" /> is <see langword="null" /> or <see cref="F:System.String.Empty" />.</exception>
-        <exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
         <exception cref="T:System.ArgumentException">
           <paramref name="name" /> is a restricted header.