Merge main into live

.github/policies/mention-owners.yml

@@ -391,9 +391,8 @@ configuration:
             then:
               - mentionUsers:
                   mentionees:
-                    - davoudeshtehari
+                    - cheenamalhotra
                     - david-engel
-                    - jrahnama
                   replyTemplate: >-
                     Tagging subscribers to this area: ${mentionees}
                   assignMentionees: False

xml/System.IO.Compression/BrotliCompressionOptions.xml

@@ -14,7 +14,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Provides compression options to be used with <see cref="T:System.IO.Compression.BrotliStream" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -51,9 +51,10 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets or sets the compression quality for a Brotli compression stream.</summary>
+        <value>The compression quality for a Brotli compression stream. The default value is 4.</value>
+        <remarks>The higher the quality, the slower the compression. The range is from 0 to 11.</remarks>
+        <exception cref="T:System.ArgumentOutOfRangeException">The value is less than 0 or greater than 11.</exception>
       </Docs>
     </Member>
   </Members>

xml/System.IO.Compression/BrotliStream.xml

@@ -77,6 +77,8 @@
         <summary>Initializes a new instance of the <see cref="T:System.IO.Compression.BrotliStream" /> class by using the specified stream and compression level.</summary>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentException">.NET 7 and later: <paramref name="compressionLevel" /> is not defined in the <see cref="System.IO.Compression.CompressionLevel" /> enumeration.</exception>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="stream" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -132,11 +134,14 @@
         <Parameter Name="leaveOpen" Type="System.Boolean" Index="2" FrameworkAlternate="net-9.0" />
       </Parameters>
       <Docs>
-        <param name="stream">To be added.</param>
-        <param name="compressionOptions">To be added.</param>
-        <param name="leaveOpen">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="stream">The stream to which compressed data is written.</param>
+        <param name="compressionOptions">The Brotli options for fine tuning the compression stream.</param>
+        <param name="leaveOpen">
+          <see langword="true" /> to leave the stream open after disposing the <see cref="T:System.IO.Compression.BrotliStream" /> object; otherwise, <see langword="false" />.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.IO.Compression.BrotliStream" /> class by using the specified stream and compression options, and optionally leaves the stream open.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="stream" /> or <paramref name="compressionOptions" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -174,6 +179,8 @@
         <summary>Initializes a new instance of the <see cref="T:System.IO.Compression.BrotliStream" /> class by using the specified stream and compression level, and optionally leaves the stream open.</summary>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentException">.NET 7 and later: <paramref name="compressionLevel" /> is not defined in the <see cref="System.IO.Compression.CompressionLevel" /> enumeration.</exception>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="stream" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">

xml/System.IO.Compression/DeflateStream.xml

@@ -362,11 +362,14 @@ You use this constructor when you want to specify whether compression efficiency
         <Parameter Name="leaveOpen" Type="System.Boolean" Index="2" FrameworkAlternate="net-9.0" />
       </Parameters>
       <Docs>
-        <param name="stream">To be added.</param>
-        <param name="compressionOptions">To be added.</param>
-        <param name="leaveOpen">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="stream">The stream to which compressed data is written.</param>
+        <param name="compressionOptions">The options for fine tuning the compression stream.</param>
+        <param name="leaveOpen">
+          <see langword="true" /> to leave the stream object open after disposing the <see cref="T:System.IO.Compression.DeflateStream" /> object; otherwise, <see langword="false" /></param>
+        <summary>Initializes a new instance of the <see cref="T:System.IO.Compression.DeflateStream" /> class by using the specified stream, compression options, and optionally leaves the stream open.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="stream" /> or <paramref name="compressionOptions" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="BaseStream">

xml/System.IO.Compression/GZipStream.xml

@@ -387,11 +387,14 @@ By default, the compression level is set to <xref:System.IO.Compression.Compress
         <Parameter Name="leaveOpen" Type="System.Boolean" Index="2" FrameworkAlternate="net-9.0" />
       </Parameters>
       <Docs>
-        <param name="stream">To be added.</param>
-        <param name="compressionOptions">To be added.</param>
-        <param name="leaveOpen">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="stream">The stream to which compressed data is written.</param>
+        <param name="compressionOptions">The options for fine tuning the compression stream.</param>
+        <param name="leaveOpen">
+          <see langword="true" /> to leave the stream object open after disposing the <see cref="T:System.IO.Compression.GZipStream" /> object; otherwise, <see langword="false" />.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.IO.Compression.GZipStream" /> class by using the specified stream, compression options, and optionally leaves the stream open.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="stream" /> or <paramref name="compressionOptions" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="BaseStream">

xml/System.IO.Compression/ZLibCompressionOptions.xml

@@ -14,7 +14,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Provides compression options to be used with <see cref="T:System.IO.Compression.ZLibStream" />, <see cref="T:System.IO.Compression.DeflateStream" />, and <see cref="T:System.IO.Compression.GZipStream" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -51,9 +51,13 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets or sets the compression level for a compression stream.</summary>
+        <value>The compression level for a compression stream. The default value is -1.</value>
+        <remarks>
+          <para>Can accept any value between -1 and 9 (inclusive). 0 gives no compression, 1 gives best speed, 9 gives best compression,</para>
+          <para>and -1 requests the default compression level, which is equivalent to 6.</para>
+        </remarks>
+        <exception cref="T:System.ArgumentOutOfRangeException">The value is less than -1 or greater than 9.</exception>
       </Docs>
     </Member>
     <Member MemberName="CompressionStrategy">
@@ -72,9 +76,10 @@
         <ReturnType>System.IO.Compression.ZLibCompressionStrategy</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets the compression algorithm for a compression stream.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentOutOfRangeException">The value is not a valid <see cref="T:System.IO.Compression.ZLibCompressionStrategy" /> value.</exception>
       </Docs>
     </Member>
   </Members>

xml/System.IO.Compression/ZLibCompressionStrategy.xml

@@ -13,7 +13,7 @@
     <BaseTypeName>System.Enum</BaseTypeName>
   </Base>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Defines the compression algorithms that can be used for <see cref="T:System.IO.Compression.DeflateStream" />, <see cref="T:System.IO.Compression.GZipStream" />, and <see cref="T:System.IO.Compression.ZLibStream" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -34,7 +34,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Used for normal data.</summary>
       </Docs>
     </Member>
     <Member MemberName="Filtered">
@@ -54,7 +54,9 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>
+          <para>Used for data produced by a filter (or predictor). The effect of Filtered is to force more Huffman coding and less string matching; it's an intermediate between Default and HuffmanOnly.</para>
+        </summary>
       </Docs>
     </Member>
     <Member MemberName="Fixed">
@@ -74,7 +76,7 @@
       </ReturnValue>
       <MemberValue>4</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.</summary>
       </Docs>
     </Member>
     <Member MemberName="HuffmanOnly">
@@ -94,7 +96,7 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Used to force Huffman encoding only (no string match).</summary>
       </Docs>
     </Member>
     <Member MemberName="RunLengthEncoding">
@@ -114,7 +116,7 @@
       </ReturnValue>
       <MemberValue>3</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Used to limit match distances to one (run-length encoding). Gives better compression for PNG image data.</summary>
       </Docs>
     </Member>
   </Members>

xml/System.IO.Compression/ZLibStream.xml

@@ -158,11 +158,14 @@
         <Parameter Name="leaveOpen" Type="System.Boolean" Index="2" FrameworkAlternate="net-9.0" />
       </Parameters>
       <Docs>
-        <param name="stream">To be added.</param>
-        <param name="compressionOptions">To be added.</param>
-        <param name="leaveOpen">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="stream">The stream to which compressed data is written.</param>
+        <param name="compressionOptions">The ZLib options for fine tuning the compression stream.</param>
+        <param name="leaveOpen">
+          <see langword="true" /> to leave the stream object open after disposing the <see cref="T:System.IO.Compression.ZLibStream" /> object; otherwise, <see langword="false" />.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.IO.Compression.ZLibStream" /> class by using the specified stream and compression options, and optionally leaves the stream open.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="stream" /> or <paramref name="compressionOptions" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="BaseStream">

xml/System.Net.Http.Headers/HttpHeaders.xml

@@ -151,6 +151,8 @@
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
+ Header names are enforced to be valid HTTP tokens, where a token is defined as any set of ASCII letters, digits, or symbols from the ``"!#$%&'*+-.^_`|~"`` set, matching [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-collected-abnf)'s definition. Non-ASCII characters are not allowed in a header name.  
+
  The header `values` will be parsed and validated.  
 
  If the specified header does not exist, the <xref:System.Net.Http.Headers.HttpHeaders.Add%2A> method inserts a new header into the list of header name/value pairs.  
@@ -166,7 +168,7 @@
 
 -or-
 
-New line characters in header values must be followed by a white-space character. 
+The header value format is invalid for this header name, or the header does not support multiple values.
         </exception>
       </Docs>
     </Member>
@@ -220,7 +222,9 @@ New line characters in header values must be followed by a white-space character
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- The header `value` will be parsed and validated.  
+ Header names are enforced to be valid HTTP tokens, where a token is defined as any set of ASCII letters, digits, or symbols from the ``"!#$%&'*+-.^_`|~"`` set, matching [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-collected-abnf)'s definition. Non-ASCII characters are not allowed in a header name.  
+
+ The header `values` will be parsed and validated.  
 
  If the specified header does not exist, the <xref:System.Net.Http.Headers.HttpHeaders.Add%2A> method inserts a new header into the list of header name/value pairs.  
 
@@ -234,7 +238,7 @@ New line characters in header values must be followed by a white-space character
 
 -or-
 
-New line characters in header values must be followed by a white-space character. 
+The header value format is invalid for this header name, or the header does not support multiple values.
         </exception>
       </Docs>
     </Member>

xml/System.Net.WebSockets/ClientWebSocketOptions.xml

@@ -463,7 +463,10 @@
         <ReturnType>System.TimeSpan</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>
+          <para>The timeout to use when waiting for the peer's PONG in response to us sending a PING; or <see cref="F:System.TimeSpan.Zero" /> or <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" /> to disable waiting for peer's response, and use an unsolicited PONG as a Keep-Alive heartbeat instead.</para>
+          <para>The default is <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />.</para>
+        </summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>

xml/System.Net.WebSockets/WebSocketCreationOptions.xml

@@ -141,7 +141,10 @@
         <ReturnType>System.TimeSpan</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>
+          <para>The timeout to use when waiting for the peer's PONG in response to us sending a PING; or <see cref="F:System.TimeSpan.Zero" /> or <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" /> to disable waiting for peer's response, and use an unsolicited PONG as a Keep-Alive heartbeat instead.</para>
+          <para>The default is <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />.</para>
+        </summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>

xml/System.Runtime.InteropServices/Marshal.xml

@@ -303,6 +303,9 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
+> [!IMPORTANT]
+> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the <xref:System.Runtime.InteropServices.NativeMemory> class on all platforms to allocate native memory. When targeting .NET 6 or earlier, use <xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A> on all platforms to allocate native memory.
+
  <xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A> is one of two memory allocation methods in the <xref:System.Runtime.InteropServices.Marshal> class. (<xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A?displayProperty=nameWithType> is the other.) This method exposes the Win32 [LocalAlloc](https://go.microsoft.com/fwlink/?LinkId=148628) function from Kernel32.dll.
 
  When <xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A> calls `LocalAlloc`, it passes a `LMEM_FIXED` flag, which causes the allocated memory to be locked in place. Also, the allocated memory is not zero-filled.
@@ -383,6 +386,9 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
+> [!IMPORTANT]
+> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the <xref:System.Runtime.InteropServices.NativeMemory> class on all platforms to allocate native memory. When targeting .NET 6 or earlier, use <xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A> on all platforms to allocate native memory.
+
  <xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A> is one of two memory allocation methods in the <xref:System.Runtime.InteropServices.Marshal> class. (<xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A?displayProperty=nameWithType> is the other.) This method exposes the Win32 [LocalAlloc](https://go.microsoft.com/fwlink/?LinkID=148628) function from Kernel32.dll.
 
  When <xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A> calls `LocalAlloc`, it passes a `LMEM_FIXED` flag, which causes the allocated memory to be locked in place. Also, the allocated memory is not zero-filled.
@@ -2656,6 +2662,9 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
+> [!IMPORTANT]
+> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the <xref:System.Runtime.InteropServices.NativeMemory> class on all platforms to allocate native memory. When targeting .NET 6 or earlier, use <xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A> on all platforms to allocate native memory.
+
  You can use <xref:System.Runtime.InteropServices.Marshal.FreeHGlobal%2A> to free any memory from the global heap allocated by <xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A>, <xref:System.Runtime.InteropServices.Marshal.ReAllocHGlobal%2A>, or any equivalent unmanaged API method. If the `hglobal` parameter is <xref:System.IntPtr.Zero?displayProperty=nameWithType> the method does nothing.
 
  <xref:System.Runtime.InteropServices.Marshal.FreeHGlobal%2A> exposes the [LocalFree](https://go.microsoft.com/fwlink/?LinkId=148640) function from Kernel32.DLL, which frees all bytes so that you can no longer use the memory pointed to by `hglobal`.
@@ -9569,6 +9578,9 @@ On .NET 6 and later versions, this method is functionally equivalent to <xref:Sy
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
+> [!IMPORTANT]
+> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the <xref:System.Runtime.InteropServices.NativeMemory> class on all platforms to allocate native memory. When targeting .NET 6 or earlier, use <xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A> on all platforms to allocate native memory.
+
  <xref:System.Runtime.InteropServices.Marshal.ReAllocHGlobal%2A> is one of two memory reallocation API methods in the <xref:System.Runtime.InteropServices.Marshal> class. (<xref:System.Runtime.InteropServices.Marshal.ReAllocCoTaskMem%2A?displayProperty=nameWithType> is the other.)
 
  This method exposes the Win32 [GlobalReAlloc](https://go.microsoft.com/fwlink/?LinkId=148780) function from Kernel32.dll. The returned pointer can differ from the original. If it is different, the contents of the original memory block have been copied to the new block, and the original memory block has been freed.