Merge pull request #11908 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

xml/System.Buffers/ArrayBufferWriter`1.xml

@@ -227,6 +227,7 @@ You must request a new buffer after calling `Advance` to continue writing more d
 You must clear the <xref:System.Buffers.ArrayBufferWriter`1> before trying to reuse it.
           ]]></format>
         </remarks>
+        <seealso cref="M:System.Buffers.ArrayBufferWriter`1.ResetWrittenCount" />
       </Docs>
     </Member>
     <Member MemberName="FreeCapacity">
@@ -385,8 +386,12 @@ This method never returns <xref:System.Span%601.Empty?displayProperty=nameWithTy
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <summary>Resets the data written to the underlying buffer without zeroing its content.</summary>
+        <remarks>
+          <para>You must reset or clear the <see cref="T:System.Buffers.ArrayBufferWriter`1" /> before trying to re-use it.</para>
+          <para>If you reset the writer using the <see cref="M:System.Buffers.ArrayBufferWriter`1.ResetWrittenCount" /> method, the underlying buffer will not be cleared.</para>
+        </remarks>
+        <seealso cref="M:System.Buffers.ArrayBufferWriter`1.Clear" />
       </Docs>
     </Member>
     <Member MemberName="WrittenCount">

xml/System.CodeDom/CodeParameterDeclarationExpressionCollection.xml

@@ -143,7 +143,7 @@
         <param name="value">An array of <see cref="T:System.CodeDom.CodeParameterDeclarationExpression" /> objects with which to initialize the collection.</param>
         <summary>Initializes a new instance of the <see cref="T:System.CodeDom.CodeParameterDeclarationExpressionCollection" /> class containing the specified array of <see cref="T:System.CodeDom.CodeParameterDeclarationExpression" /> objects.</summary>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.ArgumentNullException">one or more objects in the array are <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentNullException">One or more objects in the array are <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">

xml/System.Collections.Frozen/FrozenDictionary.xml

@@ -71,12 +71,14 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <typeparam name="TKey">To be added.</typeparam>
-        <typeparam name="TValue">To be added.</typeparam>
-        <param name="source">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <typeparam name="TKey">The type of the keys in the dictionary.</typeparam>
+        <typeparam name="TValue">The type of the values in the dictionary.</typeparam>
+        <param name="source">The key/value pairs to use to populate the dictionary.</param>
+        <summary>Creates a <see cref="T:System.Collections.Frozen.FrozenDictionary`2" /> with the specified key/value pairs.</summary>
+        <returns>A <see cref="T:System.Collections.Frozen.FrozenDictionary`2" /> that contains the specified keys and values.</returns>
+        <remarks>
+          <para>If the same key appears multiple times in the input, the latter one in the sequence takes precedence. This differs from <see cref="Overload:System.Linq.Enumerable.ToDictionary" />, with which multiple duplicate keys will result in an exception.</para>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Create&lt;TKey,TValue&gt;">
@@ -132,13 +134,15 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <typeparam name="TKey">To be added.</typeparam>
-        <typeparam name="TValue">To be added.</typeparam>
-        <param name="comparer">To be added.</param>
-        <param name="source">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <typeparam name="TKey">The type of the keys in the dictionary.</typeparam>
+        <typeparam name="TValue">The type of the values in the dictionary.</typeparam>
+        <param name="comparer">The comparer implementation to use to compare keys for equality. If <see langword="null" />, <see cref="P:System.Collections.Generic.EqualityComparer`1.Default" /> is used.</param>
+        <param name="source">The key/value pairs to use to populate the dictionary.</param>
+        <summary>Creates a <see cref="T:System.Collections.Frozen.FrozenDictionary`2" /> with the specified key/value pairs.</summary>
+        <returns>A <see cref="T:System.Collections.Frozen.FrozenDictionary`2" /> that contains the specified keys and values.</returns>
+        <remarks>
+          <para>If the same key appears multiple times in the input, the latter one in the sequence takes precedence. This differs from <see cref="Overload:System.Linq.Enumerable.ToDictionary" />, with which multiple duplicate keys will result in an exception.</para>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="ToFrozenDictionary&lt;TKey,TValue&gt;">

xml/System.Collections.Frozen/FrozenDictionary`2.xml

@@ -856,6 +856,7 @@
         <param name="index">The zero-based index in <paramref name="array" /> at which copying begins.</param>
         <summary>Copies the elements of the <see cref="T:System.Collections.ICollection" /> to an <see cref="T:System.Array" />, starting at a particular <see cref="T:System.Array" /> index.</summary>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.ICollection.IsSynchronized">
@@ -883,6 +884,7 @@
         <value>
           <see langword="true" /> if access to the <see cref="T:System.Collections.ICollection" /> is synchronized (thread safe); otherwise, <see langword="false" />.</value>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.ICollection.SyncRoot">
@@ -909,6 +911,7 @@
         <summary>Gets an object that can be used to synchronize access to the <see cref="T:System.Collections.ICollection" />.</summary>
         <value>An object that can be used to synchronize access to the <see cref="T:System.Collections.ICollection" />.</value>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionary.Add">
@@ -940,6 +943,7 @@
         <param name="value">The <see cref="T:System.Object" /> to use as the value of the element to add.</param>
         <summary>Adds an element with the provided key and value to the <see cref="T:System.Collections.IDictionary" /> object.</summary>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionary.Clear">
@@ -966,6 +970,7 @@
       <Docs>
         <summary>Removes all elements from the <see cref="T:System.Collections.IDictionary" /> object.</summary>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionary.Contains">
@@ -997,6 +1002,7 @@
         <returns>
           <see langword="true" /> if the <see cref="T:System.Collections.IDictionary" /> contains an element with the key; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionary.GetEnumerator">
@@ -1024,6 +1030,7 @@
         <summary>Returns an <see cref="T:System.Collections.IDictionaryEnumerator" /> object for the <see cref="T:System.Collections.IDictionary" /> object.</summary>
         <returns>An <see cref="T:System.Collections.IDictionaryEnumerator" /> object for the <see cref="T:System.Collections.IDictionary" /> object.</returns>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionary.IsFixedSize">
@@ -1051,6 +1058,7 @@
         <value>
           <see langword="true" /> if the <see cref="T:System.Collections.IDictionary" /> object has a fixed size; otherwise, <see langword="false" />.</value>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionary.IsReadOnly">
@@ -1078,6 +1086,7 @@
         <value>
           <see langword="true" /> if the <see cref="T:System.Collections.IDictionary" /> object is read-only; otherwise, <see langword="false" />.</value>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionary.Item">
@@ -1141,6 +1150,7 @@
         <summary>Gets an <see cref="T:System.Collections.ICollection" /> object containing the keys of the <see cref="T:System.Collections.IDictionary" /> object.</summary>
         <value>An <see cref="T:System.Collections.ICollection" /> object containing the keys of the <see cref="T:System.Collections.IDictionary" /> object.</value>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionary.Remove">
@@ -1170,6 +1180,7 @@
         <param name="key">The key of the element to remove.</param>
         <summary>Removes the element with the specified key from the <see cref="T:System.Collections.IDictionary" /> object.</summary>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionary.Values">
@@ -1196,6 +1207,7 @@
         <summary>Gets an <see cref="T:System.Collections.ICollection" /> object containing the values in the <see cref="T:System.Collections.IDictionary" /> object.</summary>
         <value>An <see cref="T:System.Collections.ICollection" /> object containing the values in the <see cref="T:System.Collections.IDictionary" /> object.</value>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IEnumerable.GetEnumerator">
@@ -1223,6 +1235,7 @@
         <summary>Returns an enumerator that iterates through a collection.</summary>
         <returns>An <see cref="T:System.Collections.IEnumerator" /> object that can be used to iterate through the collection.</returns>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="TryGetAlternateLookup&lt;TAlternateKey&gt;">

xml/System.Collections.Frozen/FrozenSet`1.xml

@@ -859,6 +859,7 @@
         <param name="index">The zero-based index in <paramref name="array" /> at which copying begins.</param>
         <summary>Copies the elements of the <see cref="T:System.Collections.ICollection" /> to an <see cref="T:System.Array" />, starting at a particular <see cref="T:System.Array" /> index.</summary>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.ICollection.IsSynchronized">
@@ -886,6 +887,7 @@
         <value>
           <see langword="true" /> if access to the <see cref="T:System.Collections.ICollection" /> is synchronized (thread safe); otherwise, <see langword="false" />.</value>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.ICollection.SyncRoot">
@@ -912,6 +914,7 @@
         <summary>Gets an object that can be used to synchronize access to the <see cref="T:System.Collections.ICollection" />.</summary>
         <value>An object that can be used to synchronize access to the <see cref="T:System.Collections.ICollection" />.</value>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IEnumerable.GetEnumerator">
@@ -939,6 +942,7 @@
         <summary>Returns an enumerator that iterates through a collection.</summary>
         <returns>An <see cref="T:System.Collections.IEnumerator" /> object that can be used to iterate through the collection.</returns>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="TryGetAlternateLookup&lt;TAlternate&gt;">

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

@@ -1594,7 +1594,7 @@ The following example demonstrates how to merge two disparate sets. This example
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- An empty set is a proper subset of any other collection. Therefore, this method returns `true` if the collection represented by the current <xref:System.Collections.Generic.HashSet%601> object is empty unless the `other` parameter is also an empty set.
+ An empty set is a subset of any other collection. Therefore, this method returns `true` if the collection represented by the current <xref:System.Collections.Generic.HashSet%601> object is empty unless the `other` parameter is also an empty set.
 
  This method always returns `false` if <xref:System.Collections.Generic.HashSet%601.Count%2A> is greater than or equal to the number of elements in `other`.
 
@@ -1676,7 +1676,7 @@ The following example demonstrates how to merge two disparate sets. This example
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- An empty set is a proper superset of any other collection. Therefore, this method returns `true` if the collection represented by the `other` parameter is empty unless the current <xref:System.Collections.Generic.HashSet%601> collection is also empty.
+ An empty set is a subset of any other collection. Therefore, this method returns `true` if the collection represented by the `other` parameter is empty unless the current <xref:System.Collections.Generic.HashSet%601> collection is also empty.
 
  This method always returns `false` if <xref:System.Collections.Generic.HashSet%601.Count%2A> is less than or equal to the number of elements in `other`.
 

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

@@ -285,7 +285,7 @@
 ## Remarks  
  If the current set is a proper subset of `other`, `other` must have at least one element that the current set does not have.  
   
- An empty set is a proper subset of any other collection. Therefore, this method returns `true` if the current set is empty, unless the `other` parameter is also an empty set.  
+ An empty set is a subset of any other collection. Therefore, this method returns `true` if the current set is empty, unless the `other` parameter is also an empty set.  
   
  This method always returns `false` if the current set has more or the same number of elements than `other`.  
   
@@ -346,7 +346,7 @@
 ## Remarks  
  If the current set is a proper superset of `other`, the current set must have at least one element that `other` does not have.  
   
- An empty set is a proper superset of any other collection. Therefore, this method returns `true` if the collection represented by the `other` parameter is empty, unless the current set is also empty.  
+ An empty set is a subset of any other collection. Therefore, this method returns `true` if the collection represented by the `other` parameter is empty, unless the current set is also empty.  
   
  This method always returns `false` if the number of elements in the current set is less than or equal to the number of elements in `other`.  
   

xml/System.Collections.Generic/OrderedDictionary`2+Enumerator.xml

@@ -130,6 +130,7 @@
         <summary>Gets both the key and the value of the current dictionary entry.</summary>
         <value>A <see cref="T:System.Collections.DictionaryEntry" /> containing both the key and the value of the current dictionary entry.</value>
         <remarks>This member is an explicit interface member implementation. It can be used only when the &lt;xref:System.Collections.Generic.OrderedDictionary`2.Enumerator&gt; instance is cast to an &lt;xref:System.Collections.IDictionaryEnumerator&gt; interface.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IDictionaryEnumerator.Key">