Automatically port Reflection.Metadata M-U APIs (#3202)

* Automatically port Reflection.Metadata M-U APIs

* Update ManifestResource.xml

* Update ManifestResourceHandleCollection.xml

* Update MemberReferenceHandleCollection.xml

* Update MetadataReader.xml

* Update MetadataReaderProvider.xml

* Update MetadataStreamOptions.xml

* Update MetadataStringComparer.xml

* Update MetadataStringDecoder.xml

* Update MethodDebugInformation.xml

* Update MethodDebugInformationHandle.xml

* Update MethodDefinitionHandle.xml

* Update NamespaceDefinitionHandle.xml

* Update ParameterHandleCollection.xml

* Update SignatureTypeCode.xml

* Update TypeDefinitionHandleCollection.xml

* Update TypeReferenceHandleCollection.xml

* Update UserStringHandle.xml

* Fixed bad cref

* Correct code example comment

Author: carlossanlop

xml/System.Reflection.Metadata/ManifestResource.xml

@@ -51,7 +51,15 @@
       <Docs>
         <summary>Gets the manifest resource attributes.</summary>
         <value>A bitwise combination of the enumeration values that specify the manifest resource attributes.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `Flags` field of the `ManifestResource` table in the [ECMA-335 Standard](https://www.ecma-international.org/publications/standards/Ecma-335.htm).
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="GetCustomAttributes">
@@ -106,7 +114,17 @@
           Gets the implementation entity handle.
         </summary>
         <value>An EntityHandle instance. If the <see cref="P:System.Reflection.Metadata.EntityHandle.IsNil" /> property is <see langword="true" />, the returned handle will have default values.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `Implementation` field of the `ManifestResource` table in the ECMA-335 Standard.
+
+If `nil`, then <xref:System.Reflection.Metadata.ManifestResource.Offset> is an offset in the PE image that contains the metadata, starting from the Resource entry in the CLI header.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Name">
@@ -132,7 +150,15 @@
       <Docs>
         <summary>Gets the resource name.</summary>
         <value>The resource name.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `Name` field of the `ManifestResource` table in the ECMA-335 Standard.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Offset">
@@ -158,7 +184,15 @@
       <Docs>
         <summary>Gets the byte offset within the referenced file at which this resource record begins.</summary>
         <value>The byte offset within the referenced file at which this resource record begins.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `Offset` field of the `ManifestResource` table in the ECMA-335 Standard.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>

xml/System.Reflection.Metadata/ManifestResourceHandleCollection.xml

@@ -37,7 +37,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Represents a collection of <see cref="T:System.Reflection.Metadata.ManifestResourceHandle" /> instances.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>

xml/System.Reflection.Metadata/MemberReferenceHandleCollection.xml

@@ -37,7 +37,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Represents a collection of <see cref="T:System.Reflection.Metadata.MemberReferenceHandle" /> instances.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>

xml/System.Reflection.Metadata/MetadataReader.xml

@@ -19,7 +19,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Reads metadata as defined by the ECMA 335 CLI specification.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -44,10 +44,18 @@
         <Parameter Name="length" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <param name="metadata">To be added.</param>
-        <param name="length">To be added.</param>
+        <param name="metadata">A pointer to the first byte in a block of metadata.</param>
+        <param name="length">The number of bytes in the block.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Reflection.Metadata.MetadataReader" /> class from the metadata stored at the given memory location.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The memory is owned by the caller. It must be kept alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReader>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -76,7 +84,17 @@
         <param name="length">To be added.</param>
         <param name="options">To be added.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Reflection.Metadata.MetadataReader" /> class from the metadata stored at the given memory location.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The memory is owned by the caller. It must be kept memory alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReader>.
+
+Use <xref:System.Reflection.Metadata.PEReaderExtensions.GetMetadataReader(System.Reflection.PortableExecutable.PEReader,System.Reflection.Metadata.MetadataReaderOptions)?displayProperty=nameWithType> to obtain metadata from a PE image.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -107,7 +125,17 @@
         <param name="options">To be added.</param>
         <param name="utf8Decoder">To be added.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Reflection.Metadata.MetadataReader" /> class from the metadata stored at the given memory location.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The memory is owned by the caller. It must be kept memory alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReader>.
+
+Use <xref:System.Reflection.Metadata.PEReaderExtensions.GetMetadataReader(System.Reflection.PortableExecutable.PEReader,System.Reflection.Metadata.MetadataReaderOptions,System.Reflection.Metadata.MetadataStringDecoder)?displayProperty=nameWithType> to obtain metadata from a PE image.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="length" /> is not positive.</exception>
         <exception cref="T:System.ArgumentNullException">

xml/System.Reflection.Metadata/MetadataReaderProvider.xml

@@ -22,8 +22,20 @@
     </Interface>
   </Interfaces>
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Provides a <see cref="T:System.Reflection.Metadata.MetadataReader" /> for metadata stored in an array of bytes, a memory block, or a stream.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+`MetadataReaderProvider` supports the following formats:
+
+ - ECMA-335 CLI (Common Language Infrastructure) metadata (<xref:System.Reflection.Metadata.MetadataReaderProvider.FromMetadataImage(System.Byte*,System.Int32)>).
+ - Edit and Continue metadata delta (<xref:System.Reflection.Metadata.MetadataReaderProvider.FromMetadataImage(System.Byte*,System.Int32)>).
+ - Portable PDB metadata (<xref:System.Reflection.Metadata.MetadataReaderProvider.FromPortablePdbImage(System.Byte*,System.Int32)>).
+
+          ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="Dispose">
@@ -51,7 +63,17 @@
       <Parameters />
       <Docs>
         <summary>Disposes all memory allocated by the reader.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+<xref:System.Reflection.Metadata.MetadataReaderProvider.Dispose> can be called multiple times (but not in parallel).
+
+It is not safe to call <xref:System.Reflection.Metadata.MetadataReaderProvider.Dispose> in parallel with any other operation on the <xref:System.Reflection.Metadata.MetadataReaderProvider> or when reading from the underlying memory.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="FromMetadataImage">
@@ -80,7 +102,15 @@
         <param name="image">Metadata image.</param>
         <summary>Creates a provider over a byte array.</summary>
         <returns>The new provider.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The content of the image is not read during the construction of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="image" /> is <see langword="null" />.</exception>
       </Docs>
@@ -112,7 +142,19 @@
         <param name="size">The size of the metadata blob.</param>
         <summary>Creates a metadata provider over an image stored in memory.</summary>
         <returns>The new metadata provider.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The memory is owned by the caller and is not released on disposal of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
+
+The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
+
+The content of the blob is not read during the construction of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="start" /> is <see cref="F:System.IntPtr.Zero" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
@@ -192,7 +234,15 @@ If <xref:System.Reflection.Metadata.MetadataStreamOptions.PrefetchMetadata?displ
         <param name="image">A portable PDB image.</param>
         <summary>Creates a portable PDB metadata provider over a byte array.</summary>
         <returns>The new portable PDB metadata provider .</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The content of the image is not read during the construction of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="image" /> is <see langword="null" />.</exception>
       </Docs>
@@ -224,7 +274,19 @@ If <xref:System.Reflection.Metadata.MetadataStreamOptions.PrefetchMetadata?displ
         <param name="size">The size of the portable PDB blob.</param>
         <summary>Creates a portable PDB metadata provider over a blob stored in memory.</summary>
         <returns>The new portable PDB metadata provider.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The memory is owned by the caller and not released on disposal of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
+
+The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
+
+The content of the blob is not read during the construction of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="start" /> is <see cref="F:System.IntPtr.Zero" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
@@ -306,7 +368,17 @@ If <xref:System.Reflection.Metadata.MetadataStreamOptions.PrefetchMetadata?displ
         <param name="utf8Decoder">The encoding to use.</param>
         <summary>Gets a <see cref="T:System.Reflection.Metadata.MetadataReader" /> from a <see cref="T:System.Reflection.Metadata.MetadataReaderProvider" />.</summary>
         <returns>A <see cref="T:System.Reflection.Metadata.MetadataReader" /> instance..</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The caller must keep the <xref:System.Reflection.Metadata.MetadataReaderProvider> undisposed throughout the lifetime of the metadata reader.
+
+If this method is called multiple times, each call with arguments equal to the arguments passed to the previous successful call returns the same instance of <xref:System.Reflection.Metadata.MetadataReader> as the previous call.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentException">The encoding of <paramref name="utf8Decoder" /> is not <see cref="T:System.Text.UTF8Encoding" />.</exception>
         <exception cref="T:System.PlatformNotSupportedException">The current platform is big-endian.</exception>
         <exception cref="T:System.IO.IOException">IO error while reading from the underlying stream.</exception>

xml/System.Reflection.Metadata/MetadataStreamOptions.xml

@@ -95,7 +95,8 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>Reads PDB metadata into memory right away.</summary>
+        <summary><para>Reads PDB metadata into memory right away.</para><para>The underlying file may be closed and even deleted after the <see cref="T:System.Reflection.Metadata.MetadataReaderProvider" /> is constructed. <see cref="T:System.Reflection.Metadata.MetadataReaderProvider" /> closes the stream automatically by the time the constructor returns unless <see cref="F:System.Reflection.Metadata.MetadataStreamOptions.LeaveOpen" /> is specified.
+</para></summary>
       </Docs>
     </Member>
   </Members>

xml/System.Reflection.Metadata/MetadataStringComparer.xml

@@ -24,8 +24,38 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Provides string comparison helpers to query strings in metadata while avoiding allocation if possible.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+No allocation is performed unless both the handle argument and the value argument contain non-ASCII text.
+
+Obtain instances using <xref:System.Reflection.Metadata.MetadataReader.StringComparer>. A default-initialized instance is useless and behaves as a `null` reference.
+
+The code is optimized so that there is no additional overhead in re-obtaining a comparer over assigning it to a local. That is to say that a construct like:
+
+```cs
+if (reader.StringComparer.Equals(typeDef.Namespace, "System") && reader.StringComparer.Equals(typeDef.Name, "Object")
+{
+    /* found System.Object */
+}
+```
+is no less efficient than:
+
+```cs
+var comparer = reader.StringComparer;
+if (comparer.Equals(typeDef.Namespace, "System") && comparer.Equals(typeDef.Name, "Object") 
+{ 
+    /* found System.Object */
+}
+```
+
+The choice between them is therefore one of style and not performance.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="Equals">

xml/System.Reflection.Metadata/MetadataStringDecoder.xml

@@ -19,8 +19,20 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Provides the <see cref="T:System.Reflection.Metadata.MetadataReader" /> with a custom mechanism for decoding byte sequences in metadata that represent text.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This type can be used as follows:
+ 
+1. To customize the treatment of invalid input. When no decoder is provided, the <xref:System.Reflection.Metadata.MetadataReader> uses the default fallback replacement with `\uFFFD`.
+
+2. To reuse existing strings instead of allocating a new one for each decoding operation.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -45,7 +57,15 @@
       <Docs>
         <param name="encoding">The encoding to use.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Reflection.Metadata.MetadataStringDecoder" /> class using the given encoding.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+To cache and reuse existing strings, create a derived class and override <xref:System.Reflection.Metadata.MetadataStringDecoder.GetString(System.Byte*,System.Int32)>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="DefaultUTF8">