Merge pull request #12409 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

xml/System.Collections.Generic/ICollection`1.xml

@@ -246,11 +246,12 @@
         <returns>
           <see langword="true" /> if <paramref name="item" /> is found in the <see cref="T:System.Collections.Generic.ICollection`1" />; otherwise, <see langword="false" />.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
- Implementations can vary in how they determine equality of objects; for example, <xref:System.Collections.Generic.List%601> uses <xref:System.Collections.Generic.Comparer%601.Default%2A?displayProperty=nameWithType>, whereas <xref:System.Collections.Generic.Dictionary%602> allows the user to specify the <xref:System.Collections.Generic.IComparer%601> implementation to use for comparing keys.
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
 
+Implementations can vary in how they determine equality of objects; for example, <xref:System.Collections.Generic.List%601> uses <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType>, whereas <xref:System.Collections.Generic.Dictionary%602> allows the user to specify the <xref:System.Collections.Generic.IEqualityComparer%601> implementation to use for comparing keys.  
+  
  ]]></format>
         </remarks>
       </Docs>
@@ -456,13 +457,14 @@
         <returns>
           <see langword="true" /> if <paramref name="item" /> was successfully removed from the <see cref="T:System.Collections.Generic.ICollection`1" />; otherwise, <see langword="false" />. This method also returns <see langword="false" /> if <paramref name="item" /> is not found in the original <see cref="T:System.Collections.Generic.ICollection`1" />.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
- Implementations can vary in how they determine equality of objects; for example, <xref:System.Collections.Generic.List%601> uses <xref:System.Collections.Generic.Comparer%601.Default%2A?displayProperty=nameWithType>, whereas, <xref:System.Collections.Generic.Dictionary%602> allows the user to specify the <xref:System.Collections.Generic.IComparer%601> implementation to use for comparing keys.
-
- In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table.
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
 
+Implementations can vary in how they determine equality of objects; for example, <xref:System.Collections.Generic.List%601> uses <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType>, whereas, <xref:System.Collections.Generic.Dictionary%602> allows the user to specify the <xref:System.Collections.Generic.IEqualityComparer%601> implementation to use for comparing keys.  
+  
+ In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table.  
+  
  ]]></format>
         </remarks>
         <exception cref="T:System.NotSupportedException">The <see cref="T:System.Collections.Generic.ICollection`1" /> is read-only.</exception>

xml/System.Collections.Generic/List`1.xml

@@ -1036,7 +1036,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- This method determines equality by using the default equality comparer, as defined by the object's implementation of the <xref:System.IEquatable%601.Equals%2A?displayProperty=nameWithType> method for `T` (the type of values in the list).
+ This method determines equality using the default equality comparer <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType> for `T`, the type of values in the list.
 
  This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is <xref:System.Collections.Generic.List%601.Count%2A>.
 
@@ -3411,7 +3411,7 @@ Public Function StartsWith(e As Employee) As Boolean
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- If type `T` implements the <xref:System.IEquatable%601> generic interface, the equality comparer is the <xref:System.IEquatable%601.Equals%2A> method of that interface; otherwise, the default equality comparer is <xref:System.Object.Equals%2A?displayProperty=nameWithType>.
+ This method determines equality using the default equality comparer <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType> for `T`, the type of values in the list.
 
  This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is <xref:System.Collections.Generic.List%601.Count%2A>.
 

xml/System.Formats.Tar/TarFile.xml

@@ -357,6 +357,7 @@
           <para>If <paramref name="destinationDirectoryName" /> or any of its parent directories is a pre-existing junction or symbolic link, the link is followed and the extraction writes to the final target folder.</para>
           <para>Files of type <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" />, <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" />, or <see cref="F:System.Formats.Tar.TarEntryType.Fifo" /> can only be extracted in Unix platforms.</para>
           <para>Elevation is required to extract a <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" /> or <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" /> to disk.</para>
+          <para>This method doesn't limit the total extracted size or the number of entries extracted from the archive. When processing archives from untrusted sources, iterate over the entries manually using <see cref="T:System.Formats.Tar.TarReader" />, and validate that the size and the number of entries are within acceptable limits for your scenario.</para>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="source" /> or <paramref name="destinationDirectoryName" /> is <see langword="null" />.</exception>
@@ -411,6 +412,7 @@ Extracting one of the tar entries would have resulted in a file outside the spec
           <para>If <paramref name="destinationDirectoryName" /> or any of its parent directories is a pre-existing junction or symbolic link, the link is followed and the extraction writes to the final target folder.</para>
           <para>Files of type <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" />, <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" />, or <see cref="F:System.Formats.Tar.TarEntryType.Fifo" /> can only be extracted in Unix platforms.</para>
           <para>Elevation is required to extract a <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" /> or <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" /> to disk.</para>
+          <para>This method doesn't limit the total extracted size or the number of entries extracted from the archive. When processing archives from untrusted sources, iterate over the entries manually using <see cref="T:System.Formats.Tar.TarReader" />, and validate that the size and the number of entries are within acceptable limits for your scenario.</para>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="sourceFileName" /> or <paramref name="destinationDirectoryName" /> is <see langword="null" />.</exception>
@@ -464,6 +466,7 @@ Extracting one of the tar entries would have resulted in a file outside the spec
           <para>If <paramref name="destinationDirectoryName" /> or any of its parent directories is a pre-existing junction or symbolic link, the link is followed and the extraction writes to the final target folder.</para>
           <para>Files of type <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" />, <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" />, or <see cref="F:System.Formats.Tar.TarEntryType.Fifo" /> can only be extracted in Unix platforms.</para>
           <para>Elevation is required to extract a <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" /> or <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" /> to disk.</para>
+          <para>This method doesn't limit the total extracted size or the number of entries extracted from the archive. When processing archives from untrusted sources, iterate over the entries manually using <see cref="T:System.Formats.Tar.TarReader" />, and validate that the size and the number of entries are within acceptable limits for your scenario.</para>
           <para>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:System.Formats.Tar.TarFile.ExtractToDirectory(System.IO.Stream,System.String,System.Boolean)" />.</para>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
@@ -522,6 +525,7 @@ Extracting one of the tar entries would have resulted in a file outside the spec
           <para>If <paramref name="destinationDirectoryName" /> or any of its parent directories is a pre-existing junction or symbolic link, the link is followed and the extraction writes to the final target folder.</para>
           <para>Files of type <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" />, <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" />, or <see cref="F:System.Formats.Tar.TarEntryType.Fifo" /> can only be extracted in Unix platforms.</para>
           <para>Elevation is required to extract a <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" /> or <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" /> to disk.</para>
+          <para>This method doesn't limit the total extracted size or the number of entries extracted from the archive. When processing archives from untrusted sources, iterate over the entries manually using <see cref="T:System.Formats.Tar.TarReader" />, and validate that the size and the number of entries are within acceptable limits for your scenario.</para>
           <para>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:System.Formats.Tar.TarFile.ExtractToDirectory(System.String,System.String,System.Boolean)" />.</para>
         </remarks>
         <exception cref="T:System.ArgumentNullException">

xml/System.Numerics/BigInteger.xml

@@ -1716,6 +1716,8 @@ The individual bytes in the `value` array should be in little-endian order, from
         <returns>The quotient and remainder of <paramref name="left" /> divided-by <paramref name="right" />.</returns>
         <remarks>To be added.</remarks>
         <inheritdoc cref="M:System.Numerics.IBinaryInteger`1.DivRem(`0,`0)" />
+        <exception cref="T:System.DivideByZeroException">
+          <paramref name="right" /> is zero.</exception>
       </Docs>
     </Member>
     <Member MemberName="DivRem">

xml/System.Numerics/IBinaryInteger`1.xml

@@ -192,6 +192,8 @@
         <summary>Computes the quotient and remainder of two values.</summary>
         <returns>The quotient and remainder of <paramref name="left" /> divided by <paramref name="right" />.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.DivideByZeroException">
+          <paramref name="right" /> is zero.</exception>
       </Docs>
     </Member>
     <Member MemberName="DivRem">

xml/System/Array.xml

@@ -5574,7 +5574,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- This method searches all the elements of a one-dimensional array for `value`. To determine whether `value` exists in `array`, the method performs an equality comparison by calling each element's `Equals` method until it finds a match. This means that if the element overrides the <xref:System.Object.Equals(System.Object)?displayProperty=nameWithType> method, that override is called.
+ This method searches all the elements of a one-dimensional array for `value`. To determine whether `value` exists in `array`, the method performs an equality comparison by using the default equality comparer <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType>.
 
  Because most arrays have a lower bound of zero, this method generally returns -1 if`value` isn't found. In the rare case that the lower bound of the array is equal to <xref:System.Int32.MinValue?displayProperty=nameWithType>(0x80000000) and `value` isn't found, this method returns <xref:System.Int32.MaxValue?displayProperty=nameWithType> (0x7FFFFFFF).
 
@@ -5673,7 +5673,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- This method searches a one-dimensional array from the element at index `startIndex` to the last element. To determine whether `value` exists in `array`, the method performs an equality comparison by calling the `Equals` method of every element until it finds a match. This means that if the element overrides the <xref:System.Object.Equals(System.Object)?displayProperty=nameWithType> method, that override is called.
+ This method searches a one-dimensional array from the element at index `startIndex` to the last element. To determine whether `value` exists in `array`, the method performs an equality comparison by using the default equality comparer <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType>.
 
  Because most arrays have a lower bound of zero, this method generally returns -1 if `value` isn't found. In the rare case that the lower bound of the array is equal to <xref:System.Int32.MinValue?displayProperty=nameWithType>(0x80000000) and `value` isn't found, this method returns <xref:System.Int32.MaxValue?displayProperty=nameWithType> (0x7FFFFFFF).
 
@@ -5783,7 +5783,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- This method searches the elements of a one-dimensional array from `startIndex` to `startIndex` plus `count` minus 1, if `count` is greater than 0. To determine whether `value` exists in `array`, the method performs an equality comparison by calling the `Equals` method of every element until it finds a match. This means that if the element overrides the <xref:System.Object.Equals%2A?displayProperty=nameWithType> method, that override is called.
+ This method searches the elements of a one-dimensional array from `startIndex` to `startIndex` plus `count` minus 1, if `count` is greater than 0. To determine whether `value` exists in `array`, the method performs an equality comparison by using the default equality comparer <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType>.
 
  Because most arrays have a lower bound of zero, this method generally returns -1 when `value` isn't found. In the rare case that the lower bound of the array is equal to <xref:System.Int32.MinValue?displayProperty=nameWithType> (0x80000000) and `value` isn't found, this method returns <xref:System.Int32.MaxValue?displayProperty=nameWithType> (0x7FFFFFFF).
 
@@ -5889,7 +5889,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- This method searches all the elements of a one-dimensional array for `value`. To determine whether `value` exists in `array`, the method performs an equality comparison by calling the `T.Equals` method on every element. This means that if `T` overrides the <xref:System.Object.Equals%2A> method, that override is called.
+ This method searches all the elements of a one-dimensional array for `value`. To determine whether `value` exists in `array`, the method performs an equality comparison by using the default equality comparer <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType>.
 
  This method is an O(`n`) operation, where `n` is the <xref:System.Array.Length%2A> of `array`.
 
@@ -5975,7 +5975,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- This method searches a one-dimensional array from the element at `startIndex` to the end of the array. To determine whether `value` exists in `array`, the method performs an equality comparison by calling the `T.Equals` method on every element. This means that if `T` overrides the <xref:System.Object.Equals%2A> method, that override is called.
+ This method searches a one-dimensional array from the element at `startIndex` to the end of the array. To determine whether `value` exists in `array`, the method performs an equality comparison by using the default equality comparer <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType>.
 
  If `startIndex` equals <xref:System.Array.Length%2A>,the method returns -1. If `startIndex` is greater than <xref:System.Array.Length%2A?displayProperty=nameWithType>, the method throws an <xref:System.ArgumentOutOfRangeException>.
 
@@ -6067,7 +6067,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- This method searches the elements of a one-dimensional array from `startIndex` to `startIndex` plus `count` minus 1, if `count` is greater than 0. To determine whether `value` exists in `array`, the method performs an equality comparison by calling the `T.Equals` method on every element. This means that if `T` overrides the <xref:System.Object.Equals%2A> method, that override is called.
+ This method searches the elements of a one-dimensional array from `startIndex` to `startIndex` plus `count` minus 1, if `count` is greater than 0. To determine whether `value` exists in `array`, the method performs an equality comparison by using the default equality comparer <xref:System.Collections.Generic.EqualityComparer%601.Default?displayProperty=nameWithType>.
 
  If `startIndex` equals <xref:System.Array.Length%2A?displayProperty=nameWithType>, the method returns -1.  If `startIndex` is greater than <xref:System.Array.Length%2A?displayProperty=nameWithType>, the method throws an <xref:System.ArgumentOutOfRangeException>.
 

xml/System/Byte.xml

@@ -710,6 +710,8 @@
         <returns>The quotient and remainder of <paramref name="left" /> divided-by <paramref name="right" />.</returns>
         <remarks>To be added.</remarks>
         <inheritdoc cref="M:System.Numerics.IBinaryInteger`1.DivRem(`0,`0)" />
+        <exception cref="T:System.DivideByZeroException">
+          <paramref name="right" /> is zero.</exception>
       </Docs>
     </Member>
     <MemberGroup MemberName="Equals">

xml/System/Int128.xml

@@ -651,6 +651,10 @@
         <returns>The quotient and remainder of <paramref name="left" /> divided-by <paramref name="right" />.</returns>
         <remarks>To be added.</remarks>
         <inheritdoc cref="M:System.Numerics.IBinaryInteger`1.DivRem(`0,`0)" />
+        <exception cref="T:System.DivideByZeroException">
+          <paramref name="right" /> is zero.</exception>
+        <exception cref="T:System.OverflowException">
+          <paramref name="left" /> is <see cref="F:System.Int128.MinValue">Int128.MinValue</see> and <paramref name="right" /> is -1.</exception>
       </Docs>
     </Member>
     <Member MemberName="Equals">

xml/System/Int16.xml

@@ -791,6 +791,8 @@
         <returns>The quotient and remainder of <paramref name="left" /> divided-by <paramref name="right" />.</returns>
         <remarks>To be added.</remarks>
         <inheritdoc cref="M:System.Numerics.IBinaryInteger`1.DivRem(`0,`0)" />
+        <exception cref="T:System.DivideByZeroException">
+          <paramref name="right" /> is zero.</exception>
       </Docs>
     </Member>
     <MemberGroup MemberName="Equals">