Porting .NET 10 docs from assemblies that don't use /// as source of truth (#11876)

* System.Buffers docs

* System.Collections docs

* System.ComponentModel.DataAnnotations docs

* System.ComponentModel docs

* System.Composition docs

* System.Data docs

* System.Diagnostics docs

* System.DirectoryServices docs

* System.Formats.Tar docs

* System.IO.Compression docs

* System.IO.Hashing docs

* System.IO.Packaging docs

* System.Linq docs

* System.Management docs

* System.Net docs

* System.Numerics docs

* System.Reflection docs

* System.Runtime.InteropServices docs

* System.Runtime.Serialization docs

* System.Security.Claims docs

* System.Security.Cryptography docs

* System.Text.Json docs

* System.Text.RegularExpressions docs

* System.Text docs

* System.Threading docs

* System.Xml docs

* System docs

* Fix some warnings

* Fix bad xml escaping of remarks

* Apply feedback from review

* Make multi-line elements easier to review

* More indenting fixes

* Try again to fix warnings

* system.io.compression fixups

* random fixes

* STJ and BinaryData edits

* fix xml

* Address feedback

* a few more edits

---------

Co-authored-by: Genevieve Warren <[email protected]>

Author: ericstj

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/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">

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

@@ -92,6 +92,7 @@
         <returns>
           <see langword="true" /> if <paramref name="key" /> is found in the <see cref="T:System.Collections.Generic.ICollection`1" />; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="CopyTo">
@@ -122,6 +123,7 @@
         <param name="arrayIndex">The zero-based index in <paramref name="array" /> at which copying begins.</param>
         <summary>Copies the elements of the <see cref="T:System.Collections.Generic.ICollection`1" /> 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="Count">
@@ -149,6 +151,7 @@
         <summary>Gets the number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.</summary>
         <value>The number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.</value>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="GetEnumerator">
@@ -500,6 +503,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">
@@ -526,6 +530,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>This member is an explicit interface member implementation. It can be used only when the &lt;xref:System.Collections.Generic.OrderedDictionary`2.KeyCollection&gt; instance is cast to an &lt;xref:System.Collections.ICollection&gt; interface.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.ICollection.SyncRoot">
@@ -557,6 +562,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>This member is an explicit interface member implementation. It can be used only when the &lt;xref:System.Collections.Generic.OrderedDictionary`2.KeyCollection&gt; instance is cast to an &lt;xref:System.Collections.ICollection&gt; interface.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IEnumerable.GetEnumerator">
@@ -583,6 +589,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>This member is an explicit interface member implementation. It can be used only when the &lt;xref:System.Collections.Generic.OrderedDictionary`2.KeyCollection&gt; instance is cast to an &lt;xref:System.Collections.IEnumerable&gt; interface.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.Add">
@@ -638,6 +645,7 @@
       <Docs>
         <summary>Removes all items from the <see cref="T:System.Collections.IList" />.</summary>
         <remarks>This member is an explicit interface member implementation. It can be used only when the &lt;xref:System.Collections.Generic.OrderedDictionary`2.KeyCollection&gt; instance is cast to an &lt;xref:System.Collections.IList&gt; interface.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.Contains">
@@ -668,6 +676,7 @@
         <returns>
           <see langword="true" /> if the <see cref="T:System.Object" /> is found in the <see cref="T:System.Collections.IList" />; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.IndexOf">
@@ -697,6 +706,7 @@
         <summary>Determines the index of a specific item in the <see cref="T:System.Collections.IList" />.</summary>
         <returns>The index of <paramref name="value" /> if found in the list; otherwise, -1.</returns>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.Insert">
@@ -727,6 +737,7 @@
         <param name="value">The object to insert into the <see cref="T:System.Collections.IList" />.</param>
         <summary>Inserts an item into the <see cref="T:System.Collections.IList" /> at the specified index.</summary>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.IsFixedSize">
@@ -753,6 +764,7 @@
         <value>
           <see langword="true" /> if the <see cref="T:System.Collections.IList" /> has a fixed size; otherwise, <see langword="false" />.</value>
         <remarks>This member is an explicit interface member implementation. It can be used only when the &lt;xref:System.Collections.Generic.OrderedDictionary`2.KeyCollection&gt; instance is cast to an &lt;xref:System.Collections.IList&gt; interface.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.IsReadOnly">
@@ -779,6 +791,7 @@
         <value>
           <see langword="true" /> if the <see cref="T:System.Collections.IList" /> is read-only; otherwise, <see langword="false" />.</value>
         <remarks>This member is an explicit interface member implementation. It can be used only when the &lt;xref:System.Collections.Generic.OrderedDictionary`2.KeyCollection&gt; instance is cast to an &lt;xref:System.Collections.IList&gt; interface.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.Item">
@@ -843,6 +856,7 @@
         <param name="value">The object to remove from the <see cref="T:System.Collections.IList" />.</param>
         <summary>Removes the first occurrence of a specific object from the <see cref="T:System.Collections.IList" />.</summary>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.RemoveAt">
@@ -871,6 +885,7 @@
         <param name="index">The zero-based index of the item to remove.</param>
         <summary>Removes the <see cref="T:System.Collections.IList" /> item at the specified index.</summary>
         <remarks>To be added.</remarks>
+        <inheritdoc />
       </Docs>
     </Member>
   </Members>