Automatically port Reflection.Metadata A-D APIs (#3200)

* Automatically port Reflection.Metadata A-D APIs

* suggestion by Thraka

Co-Authored-By: Andy De George <2672110+Thraka@users.noreply.github.com>

xml/System.Reflection.Metadata/AssemblyFile.xml

@@ -52,7 +52,15 @@
         <summary>Gets a value that indicates whether the file contains metadata.</summary>
         <value>
           <see langword="true" /> if the file contains metadata, <see langword="false" /> otherwise.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `Flags` field of the `File` table in the ECMA-335 Standard.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="GetCustomAttributes">
@@ -105,7 +113,15 @@
       <Docs>
         <summary>Gets the hash value of the file content calculated using <see cref="P:System.Reflection.Metadata.AssemblyDefinition.HashAlgorithm" />.</summary>
         <value>A <see cref="T:System.Reflection.Metadata.BlobHandle" /> instance representing the hash value of the file content.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `HashValue` field of the `File` table in the ECMA-335 Standard.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Name">
@@ -131,7 +147,15 @@
       <Docs>
         <summary>Gets the file name, including its extension.</summary>
         <value>A <see cref="T:System.Reflection.Metadata.StringHandle" /> instance representing the file name with its extension.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `Name` field of the `File` table in the ECMA-335 Standard.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>

xml/System.Reflection.Metadata/AssemblyFileHandleCollection.xml

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

xml/System.Reflection.Metadata/AssemblyReferenceHandleCollection.xml

@@ -37,7 +37,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>A collection of assembly references.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>

xml/System.Reflection.Metadata/BlobBuilder.xml

@@ -850,7 +850,19 @@
       <Docs>
         <param name="value">The value to write.</param>
         <summary>Implements compressed unsigned integer encoding as defined by ECMA-335-II chapter 23.2: Blobs and signatures.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If the value lies between 0 (0x00) and 127 (0x7F), inclusive, encode as a one-byte integer (bit 7 is clear, value held in bits 6 through 0).
+
+If the value lies between 28 (0x80) and 214 - 1 (0x3FFF), inclusive, encode as a 2-byte integer with bit 15 set, bit 14 clear (value held in bits 13 through 0).
+
+Otherwise, encode as a 4-byte integer, with bit 31 set, bit 30 set, bit 29 clear (value held in bits 28 through 0).
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="value" /> can't be represented as a compressed unsigned integer.</exception>
         <exception cref="T:System.InvalidOperationException">The builder is not writable; it has been linked with another one.</exception>
@@ -880,7 +892,19 @@
       <Docs>
         <param name="value">The value to write.</param>
         <summary>Implements compressed signed integer encoding as defined by ECMA-335-II chapter 23.2: Blobs and signatures.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If the value lies between -64 (0xFFFFFFC0) and 63 (0x3F), inclusive, encode as a one-byte integer:  bit 7 clear, value bits 5 through 0 held in bits 6 through 1, sign bit (value bit 31) in bit 0.
+
+If the value lies between -8192 (0xFFFFE000) and 8191 (0x1FFF), inclusive, encode as a two-byte integer: 15 set, bit 14 clear, value bits 12 through 0 held in bits 13 through 1, sign bit(value bit 31) in bit 0.
+
+If the value lies between -268435456 (0xF000000) and 268435455 (0x0FFFFFFF), inclusive, encode as a four-byte integer: 31 set, 30 set, bit 29 clear, value bits 27 through 0 held in bits 28 through 1, sign bit(value bit 31) in bit 0.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="value" /> can't be represented as a compressed signed integer.</exception>
         <exception cref="T:System.InvalidOperationException">The builder is not writable; it has been linked with another one.</exception>
@@ -1341,7 +1365,17 @@
       <Docs>
         <param name="value">To be added.</param>
         <summary>Writes a string in SerString format (see ECMA-335-II 23.3 Custom attributes).</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The string is UTF8 encoded and prefixed by the its size in bytes.
+
+A `null` string is represented as a single byte 0xFF.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">Builder is not writable, it has been linked with another one.</exception>
       </Docs>
     </Member>
@@ -1537,7 +1571,19 @@
       <Docs>
         <param name="value">To be added.</param>
         <summary>Writes a string in User String (#US) heap format (see ECMA-335-II 24.2.4 #US and #Blob heaps).</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The string is UTF16 encoded and prefixed by the its size in bytes.
+
+This final byte holds the value 1 if and only if any UTF16 character within the string has any bit set in its top byte, or its low byte is any of the following: 0x01-0x08, 0x0E-0x1F, 0x27, 0x2D, 0x7F. Otherwise, it holds 0.
+
+The 1 signifies Unicode characters that require handling beyond that normally provided for 8-bit encoding sets.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">Builder is not writable, it has been linked with another one.</exception>
       </Docs>
     </Member>

xml/System.Reflection.Metadata/BlobReader.xml

@@ -134,7 +134,15 @@
         <param name="value">The byte value to find.</param>
         <summary>Searches for a specified byte in the blob following the current position.</summary>
         <returns>The index relative to the current position, or -1 if the byte is not found in the blob following the current position.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Doesn't change the current position.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Length">
@@ -217,7 +225,15 @@
       <Docs>
         <summary>Reads a Blob heap handle encoded as a compressed integer.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Blobs that contain references to other blobs are used in Portable PDB format, for example <xref:System.Reflection.Metadata.Document.Name>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="ReadBoolean">
@@ -503,7 +519,18 @@
       <Docs>
         <summary>Reads a <see cref="T:System.Decimal" /> number.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Decimal number is encoded in 13 bytes as follows:
+
+ - byte 0: highest bit indicates sign (1 for negative, 0 for non-negative); the remaining 7 bits encode scale.
+ - bytes 1..12: 96-bit unsigned integer in little endian encoding.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.BadImageFormatException">The data at the current position was not a valid <see cref="T:System.Decimal" /> number.</exception>
       </Docs>
     </Member>
@@ -720,7 +747,15 @@
       <Docs>
         <summary>Reads a string encoded as a compressed integer containing its length followed by its contents in UTF8. Null strings are encoded as a single 0xFF byte.</summary>
         <returns>A string value, or <see langword="null" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Defined as a 'SerString' in the ECMA CLI specification.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.BadImageFormatException">The encoding is invalid.</exception>
       </Docs>
     </Member>

xml/System.Reflection.Metadata/BlobWriter.xml

@@ -764,7 +764,19 @@
       <Docs>
         <param name="value">To be added.</param>
         <summary>Implements compressed unsigned integer encoding as defined by ECMA-335-II chapter 23.2: Blobs and signatures.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If the value lies between 0 (0x00) and 127 (0x7F), inclusive, encode as a one-byte integer (bit 7 is clear, value held in bits 6 through 0).
+
+If the value lies between 28 (0x80) and 214 - 1 (0x3FFF), inclusive, encode as a 2-byte integer with bit 15 set, bit 14 clear (value held in bits 13 through 0).
+
+Otherwise, encode as a 4-byte integer, with bit 31 set, bit 30 set, bit 29 clear (value held in bits 28 through 0).
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="value" /> can't be represented as a compressed unsigned integer.</exception>
       </Docs>
@@ -793,7 +805,19 @@
       <Docs>
         <param name="value">To be added.</param>
         <summary>Implements compressed signed integer encoding as defined by ECMA-335-II chapter 23.2: Blobs and signatures.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If the value lies between -64 (0xFFFFFFC0) and 63 (0x3F), inclusive, encode as a one-byte integer: bit 7 clear, value bits 5 through 0 held in bits 6 through 1, sign bit (value bit 31) in bit 0.
+
+If the value lies between -8192 (0xFFFFE000) and 8191 (0x1FFF), inclusive, encode as a two-byte integer: 15 set, bit 14 clear, value bits 12 through 0 held in bits 13 through 1, sign bit(value bit 31) in bit 0.
+
+If the value lies between -268435456 (0xF000000) and 268435455 (0x0FFFFFFF), inclusive, encode as a four-byte integer: 31 set, 30 set, bit 29 clear, value bits 27 through 0 held in bits 28 through 1, sign bit(value bit 31) in bit 0.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="value" /> can't be represented as a compressed signed integer.</exception>
       </Docs>
@@ -1151,7 +1175,17 @@
       <Docs>
         <param name="str">To be added.</param>
         <summary>Writes a string in SerString format (see ECMA-335-II 23.3 Custom attributes).</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The string is UTF8 encoded and prefixed by the its size in bytes.
+
+A `null` string is represented as a single byte 0xFF.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">The builder is not writable; it has been linked with another one.</exception>
       </Docs>
     </Member>
@@ -1341,7 +1375,19 @@
       <Docs>
         <param name="value">To be added.</param>
         <summary>Writes a string in User String (#US) heap format (see ECMA-335-II 24.2.4 #US and #Blob heaps).</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The string is UTF16 encoded and prefixed by the its size in bytes.
+
+This final byte holds the value 1 if and only if any UTF16 character within the string has any bit set in its top byte, or its low byte is any of the following: 0x01-0x08, 0x0E-0x1F, 0x27, 0x2D, 0x7F. Otherwise, it holds 0.
+
+The 1 signifies Unicode characters that require handling beyond that normally provided for 8-bit encoding sets.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">Builder is not writable, it has been linked with another one.</exception>
       </Docs>
     </Member>

xml/System.Reflection.Metadata/Constant.xml

@@ -51,7 +51,15 @@
       <Docs>
         <summary>Gets the parent handle (<see cref="T:System.Reflection.Metadata.ParameterHandle" />, <see cref="T:System.Reflection.Metadata.FieldDefinitionHandle" />, or <see cref="T:System.Reflection.Metadata.PropertyDefinitionHandle" />).</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `Parent` field of the `Constant` table in the ECMA-335 Standard.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="TypeCode">
@@ -77,7 +85,15 @@
       <Docs>
         <summary>Gets a type code that identifies the type of the constant value.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `Type` field of the `Constant` table in the ECMA-335 Standard.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Value">
@@ -103,7 +119,15 @@
       <Docs>
         <summary>Gets the constant value.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Corresponds to the `Value` field of the `Constant` table in the ECMA-335 Standard.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>