Port System.Reflection.Metadata source code comments to Docs (L-Metadata* files) (#2333)

* Port System.Reflection.Metadata source code comments to Docs (L-Metadata* files)

* Proper language for a struct with default value.

* Apply suggestions from code review

Suggestions provided by mairaw

Co-Authored-By: carlossanlop <[email protected]>

* Addressed mairaw comments.

Author: carlossanlop

xml/System.Reflection.Metadata/LocalConstant.xml

@@ -72,10 +72,10 @@
         <ReturnType>System.Reflection.Metadata.BlobHandle</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the constant signature.</summary>
+        <value>The constant signature.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Reflection.Metadata/ManifestResource.xml

@@ -49,8 +49,8 @@
         <ReturnType>System.Reflection.ManifestResourceAttributes</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the manifest resource attributes.</summary>
+        <value>A bitwise combination of the enumeration values that specify the manifest resource atttributes.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -102,8 +102,10 @@
         <ReturnType>System.Reflection.Metadata.EntityHandle</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>
+          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>
       </Docs>
     </Member>
@@ -128,8 +130,8 @@
         <ReturnType>System.Reflection.Metadata.StringHandle</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the resource name.</summary>
+        <value>The resource name.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -154,10 +156,10 @@
         <ReturnType>System.Int64</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <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>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Reflection.Metadata/MemberReference.xml

@@ -205,9 +205,10 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Determines if the member reference is to a method or field.</summary>
+        <returns>One of the enumeration values that indicates the kind of member reference.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.BadImageFormatException">The member reference signature is invalid.</exception>
       </Docs>
     </Member>
     <Member MemberName="Name">
@@ -257,8 +258,8 @@
         <ReturnType>System.Reflection.Metadata.EntityHandle</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the parent entity handle.</summary>
+        <value>An entity handle 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>
       </Docs>
     </Member>
@@ -283,10 +284,10 @@
         <ReturnType>System.Reflection.Metadata.BlobHandle</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets a handle to the signature blob.</summary>
+        <value>A handle to the signature blob.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Reflection.Metadata/MetadataKind.xml

@@ -44,7 +44,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>CLI metadata.</summary>
       </Docs>
     </Member>
     <Member MemberName="ManagedWindowsMetadata">
@@ -69,7 +69,7 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Windows metadata generated by managed compilers.</summary>
       </Docs>
     </Member>
     <Member MemberName="WindowsMetadata">
@@ -94,8 +94,8 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Windows metadata.</summary>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Reflection.Metadata/MetadataReader.xml

@@ -46,7 +46,7 @@
       <Docs>
         <param name="metadata">To be added.</param>
         <param name="length">To be added.</param>
-        <summary>To be added.</summary>
+        <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>
       </Docs>
     </Member>
@@ -75,7 +75,7 @@
         <param name="metadata">To be added.</param>
         <param name="length">To be added.</param>
         <param name="options">To be added.</param>
-        <summary>To be added.</summary>
+        <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>
       </Docs>
     </Member>
@@ -106,8 +106,13 @@
         <param name="length">To be added.</param>
         <param name="options">To be added.</param>
         <param name="utf8Decoder">To be added.</param>
-        <summary>To be added.</summary>
+        <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>
+        <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="length" /> is not positive.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="metadata" /> is <see langword="null" />.</exception>
+        <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.BadImageFormatException">Bad metadata header.</exception>
       </Docs>
     </Member>
     <Member MemberName="AssemblyFiles">
@@ -233,8 +238,8 @@
         <ReturnType>System.Reflection.Metadata.DebugMetadataHeader</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the information decoded from #Pdb stream, or <see langword="null" /> if the stream is not present.</summary>
+        <value>The information decoded from #Pdb stream, or <see langword="null" /> if the stream is not present.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1830,8 +1835,8 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets a value that indicates whether the metadata represents an assembly.</summary>
+        <value><see langword="true" /> if the metadata represents an assembly; otherwise, <see langword="false" />.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1983,8 +1988,8 @@
         <ReturnType>System.Reflection.Metadata.MetadataKind</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the metadata kind.</summary>
+        <value>One of the enumeration values that specifies the metadata kind.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2007,8 +2012,8 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the length of the underlying data.</summary>
+        <value>The length of the underlying data.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2030,8 +2035,8 @@
         <ReturnType>System.Byte*</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the pointer to the underlying data.</summary>
+        <value>The pointer to the underlying data.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2056,8 +2061,8 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the version string read from metadata header.</summary>
+        <value>The version string read from metadata header.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2133,8 +2138,8 @@
         <ReturnType>System.Reflection.Metadata.MetadataReaderOptions</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the <see cref="F:System.Reflection.Metadata.MetadataReaderOptions" /> passed to the constructor.</summary>
+        <value>A bitwise combination of the enumeration values that describes the <see cref="F:System.Reflection.Metadata.MetadataReaderOptions" /> enum value.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2185,8 +2190,8 @@
         <ReturnType>System.Reflection.Metadata.MetadataStringComparer</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the comparer used to compare strings stored in metadata.</summary>
+        <value>The comparer used to compare strings stored in metadata.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2261,10 +2266,10 @@
         <ReturnType>System.Reflection.Metadata.MetadataStringDecoder</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the decoder used by the reader to produce string instances from UTF8-encoded byte sequences.</summary>
+        <value>The decoder used by the reader to produce string instances from UTF8-encoded byte sequences.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Reflection.Metadata/MetadataReaderOptions.xml

@@ -49,7 +49,7 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Windows Runtime projections are enabled (on by default).</summary>
       </Docs>
     </Member>
     <Member MemberName="Default">
@@ -74,7 +74,7 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The options that are used when a <see cref="T:System.Reflection.Metadata.MetadataReader" /> is obtained via an overload that does not take a <see cref="T:System.Reflection.Metadata.MetadataReaderOptions" /> argument.</summary>
       </Docs>
     </Member>
     <Member MemberName="None">
@@ -99,7 +99,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>All options are disabled.</summary>
       </Docs>
     </Member>
   </Members>