From f73ea3208834ef42a4d69c9fcf3e5b0f2eafd32e Mon Sep 17 00:00:00 2001
From: carlossanlop <calope@microsoft.com>
Date: Mon, 16 Sep 2019 11:45:58 -0700
Subject: [PATCH 1/5] Automatically port
 Reflection.PortableExecutable.DebugDirectory*

---
 .../DebugDirectoryBuilder.xml                 | 51 +++++++------
 .../DebugDirectoryEntry.xml                   | 28 ++++---
 .../DebugDirectoryEntryType.xml               | 75 +++++++++++++++++--
 3 files changed, 116 insertions(+), 38 deletions(-)

diff --git a/xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml b/xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml
index f540465632e..6dc0016a15d 100644
--- a/xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml
+++ b/xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml
@@ -65,11 +65,14 @@
         <Parameter Name="portablePdbVersion" Type="System.UInt16" Index="2" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="pdbPath">To be added.</param>
-        <param name="pdbContentId">To be added.</param>
-        <param name="portablePdbVersion">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="pdbPath">Path to the PDB. Shall not be empty.</param>
+        <param name="pdbContentId">Unique id of the PDB content.</param>
+        <param name="portablePdbVersion">Version of Portable PDB format (e.g. 0x0100 for 1.0), or 0 if the PDB is not portable.</param>
+        <summary>Adds a CodeView entry.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="pdbPath" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="pdbPath" /> contains NUL character.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="portablePdbVersion" /> is smaller than 0x0100.</exception>
       </Docs>
     </Member>
     <Member MemberName="AddEmbeddedPortablePdbEntry">
@@ -95,10 +98,12 @@
         <Parameter Name="portablePdbVersion" Type="System.UInt16" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="debugMetadata">To be added.</param>
-        <param name="portablePdbVersion">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="debugMetadata">Portable PDB metadata builder.</param>
+        <param name="portablePdbVersion">Version of Portable PDB format (e.g. 0x0100 for 1.0).</param>
+        <summary>Adds Embedded Portable PDB entry.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="debugMetadata" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="portablePdbVersion" /> is smaller than 0x0100.</exception>
       </Docs>
     </Member>
     <Member MemberName="AddEntry">
@@ -123,10 +128,10 @@
         <Parameter Name="stamp" Type="System.UInt32" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="type">To be added.</param>
-        <param name="version">To be added.</param>
-        <param name="stamp">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="type">Entry type.</param>
+        <param name="version">Entry version.</param>
+        <param name="stamp">Entry stamp.</param>
+        <summary>Adds an entry.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -157,13 +162,13 @@
         <Parameter Name="dataSerializer" Type="System.Action&lt;System.Reflection.Metadata.BlobBuilder,TData&gt;" Index="4" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <typeparam name="TData">To be added.</typeparam>
-        <param name="type">To be added.</param>
-        <param name="version">To be added.</param>
-        <param name="stamp">To be added.</param>
-        <param name="data">To be added.</param>
-        <param name="dataSerializer">To be added.</param>
-        <summary>To be added.</summary>
+        <typeparam name="TData">Type of data passed to <paramref name="dataSerializer" />.</typeparam>
+        <param name="type">Entry type.</param>
+        <param name="version">Entry version.</param>
+        <param name="stamp">Entry stamp.</param>
+        <param name="data">Data passed to <paramref name="dataSerializer" />.</param>
+        <param name="dataSerializer">Serializes data to a <see cref="T:System.Reflection.Metadata.BlobBuilder" />.</param>
+        <summary>Adds an entry.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -188,10 +193,12 @@
         <Parameter Name="checksum" Type="System.Collections.Immutable.ImmutableArray&lt;System.Byte&gt;" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="algorithmName">To be added.</param>
-        <param name="checksum">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="algorithmName">Hash algorithm name (e.g. "SHA256").</param>
+        <param name="checksum">Checksum.</param>
+        <summary>Adds PDB checksum entry.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="algorithmName" /> or <paramref name="checksum" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="algorithmName" /> or <paramref name="checksum" /> is empty.</exception>
       </Docs>
     </Member>
     <Member MemberName="AddReproducibleEntry">
@@ -214,7 +221,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Adds Reproducible entry.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
diff --git a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml
index 0a3ef9e5a5d..128caec0834 100644
--- a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml
+++ b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml
@@ -23,7 +23,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Identifies the location, size and format of a block of debug information.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -84,7 +84,7 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The file pointer to the debug data.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -109,7 +109,7 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The address of the debug data when loaded, relative to the image base.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -134,7 +134,7 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The size of the debug data (not including the debug directory itself).</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -158,7 +158,7 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary><see langword="true" /> if the entry is a <see cref="F:System.Reflection.PortableExecutable.DebugDirectoryEntryType.CodeView" /> entry pointing to a Portable PDB.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -183,7 +183,7 @@
         <ReturnType>System.UInt16</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The major version number of the debug data format.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -208,7 +208,7 @@
         <ReturnType>System.UInt16</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The minor version number of the debug data format.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -233,9 +233,17 @@
         <ReturnType>System.UInt32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The time and date that the debug data was created if the PE/COFF file is not deterministic, otherwise a value based on the hash of the content.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The algorithm used to calculate this value is an implementation detail of the tool that produced the file.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Type">
@@ -258,7 +266,7 @@
         <ReturnType>System.Reflection.PortableExecutable.DebugDirectoryEntryType</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The format of debugging information.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
diff --git a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
index 8388cd19afc..fadcc70a9d6 100644
--- a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
+++ b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
@@ -42,7 +42,16 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Associated PDB file description.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#codeview-debug-directory-entry-type-2 for specification.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Coff">
@@ -66,7 +75,16 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The COFF debug information (line numbers, symbol table, and string table).</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This type of debug information is also pointed to by fields in the file headers.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="EmbeddedPortablePdb">
@@ -89,7 +107,21 @@
       </ReturnValue>
       <MemberValue>17</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The entry points to a blob containing Embedded Portable PDB.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The Embedded Portable PDB blob has the following format:
+ 
+  blob ::= uncompressed-size data 
+  Data spans the remainder of the blob and contains a Deflate-compressed Portable PDB.
+ 
+See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#embedded-portable-pdb-debug-directory-entry-type-17 for specification.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="PdbChecksum">
@@ -110,7 +142,20 @@
       </ReturnValue>
       <MemberValue>19</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The entry stores crypto hash of the content of the symbol file the PE/COFF file was built with.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The hash can be used to validate that a given PDB file was built with the PE/COFF file and not altered in any way.
+
+More than one entry can be present, in case multiple PDBs were produced during the build of the PE/COFF file (e.g. private and public symbols).
+ 
+ See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#pdb-checksum-debug-directory-entry-type-19 for specification.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Reproducible">
@@ -134,7 +179,25 @@
       </ReturnValue>
       <MemberValue>16</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Presence of this entry indicates deterministic PE/COFF file.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The tool that produced the deterministic PE/COFF file guarantees that the entire content of the file is based solely on documented inputs given to the tool (such as source files, resource files, compiler options, etc.) rather than ambient environment variables (such as the current time, the operating system, the bitness of the process running the tool, etc.).
+
+The value of field `TimeDateStamp` in COFF File Header of a deterministic PE/COFF file does not indicate the date and time when the file was produced and should not be interpreted that way.
+
+Instead the value of the field is derived from a hash of the file content. The algorithm to calculate this value is an implementation detail of the tool that produced the file.
+
+The debug directory entry of type <xref:System.Reflection.PortableExecutable.DebugDirectoryEntryType.Reproducible> must have all fields, except for Type zeroed.
+
+See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#deterministic-debug-directory-entry-type-16 for specification.
+ 
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Unknown">
@@ -158,7 +221,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>An unknown value that is ignored by all tools.</summary>
       </Docs>
     </Member>
   </Members>

From 804feb50417527af0bd48ce9fb31481c121ff395 Mon Sep 17 00:00:00 2001
From: Ron Petrusha <ronpet@microsoft.com>
Date: Thu, 26 Sep 2019 13:53:45 -0700
Subject: [PATCH 2/5] Made direct edits.

---
 .../DebugDirectoryBuilder.xml                 | 44 +++++++++----------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml b/xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml
index 6dc0016a15d..f6751828cd8 100644
--- a/xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml
+++ b/xml/System.Reflection.PortableExecutable/DebugDirectoryBuilder.xml
@@ -37,7 +37,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Reflection.PortableExecutable.DebugDirectoryBuilder" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -65,13 +65,13 @@
         <Parameter Name="portablePdbVersion" Type="System.UInt16" Index="2" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="pdbPath">Path to the PDB. Shall not be empty.</param>
-        <param name="pdbContentId">Unique id of the PDB content.</param>
-        <param name="portablePdbVersion">Version of Portable PDB format (e.g. 0x0100 for 1.0), or 0 if the PDB is not portable.</param>
+        <param name="pdbPath">The path to the PDB. It should not be empty.</param>
+        <param name="pdbContentId">The unique id of the PDB content.</param>
+        <param name="portablePdbVersion">The version of Portable PDB format (e.g. 0x0100 for 1.0), or 0 if the PDB is not portable.</param>
         <summary>Adds a CodeView entry.</summary>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException"><paramref name="pdbPath" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="pdbPath" /> contains NUL character.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="pdbPath" /> contains a NUL character.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="portablePdbVersion" /> is smaller than 0x0100.</exception>
       </Docs>
     </Member>
@@ -98,9 +98,9 @@
         <Parameter Name="portablePdbVersion" Type="System.UInt16" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="debugMetadata">Portable PDB metadata builder.</param>
-        <param name="portablePdbVersion">Version of Portable PDB format (e.g. 0x0100 for 1.0).</param>
-        <summary>Adds Embedded Portable PDB entry.</summary>
+        <param name="debugMetadata">A Portable PDB metadata builder.</param>
+        <param name="portablePdbVersion">The version of Portable PDB format (e.g. 0x0100 for 1.0).</param>
+        <summary>Adds an Embedded Portable PDB entry.</summary>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException"><paramref name="debugMetadata" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="portablePdbVersion" /> is smaller than 0x0100.</exception>
@@ -128,10 +128,10 @@
         <Parameter Name="stamp" Type="System.UInt32" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="type">Entry type.</param>
-        <param name="version">Entry version.</param>
-        <param name="stamp">Entry stamp.</param>
-        <summary>Adds an entry.</summary>
+        <param name="type">The entry type.</param>
+        <param name="version">The entry version.</param>
+        <param name="stamp">The entry stamp.</param>
+        <summary>Adds an entry of the specified type.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -162,13 +162,13 @@
         <Parameter Name="dataSerializer" Type="System.Action&lt;System.Reflection.Metadata.BlobBuilder,TData&gt;" Index="4" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <typeparam name="TData">Type of data passed to <paramref name="dataSerializer" />.</typeparam>
-        <param name="type">Entry type.</param>
-        <param name="version">Entry version.</param>
-        <param name="stamp">Entry stamp.</param>
-        <param name="data">Data passed to <paramref name="dataSerializer" />.</param>
-        <param name="dataSerializer">Serializes data to a <see cref="T:System.Reflection.Metadata.BlobBuilder" />.</param>
-        <summary>Adds an entry.</summary>
+        <typeparam name="TData">The type of the data passed to <paramref name="dataSerializer" />.</typeparam>
+        <param name="type">The entry type.</param>
+        <param name="version">The entry version.</param>
+        <param name="stamp">The entry stamp.</param>
+        <param name="data">The data to pass to <paramref name="dataSerializer" />.</param>
+        <param name="dataSerializer">A serializer for serializing data to a <see cref="T:System.Reflection.Metadata.BlobBuilder" />.</param>
+        <summary>Adds an entry of the specified type and serializes its data.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -193,8 +193,8 @@
         <Parameter Name="checksum" Type="System.Collections.Immutable.ImmutableArray&lt;System.Byte&gt;" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="algorithmName">Hash algorithm name (e.g. "SHA256").</param>
-        <param name="checksum">Checksum.</param>
+        <param name="algorithmName">The hash algorithm name (for example, "SHA256").</param>
+        <param name="checksum">The checksum.</param>
         <summary>Adds PDB checksum entry.</summary>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException"><paramref name="algorithmName" /> or <paramref name="checksum" /> is <see langword="null" />.</exception>
@@ -221,7 +221,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>Adds Reproducible entry.</summary>
+        <summary>Adds a reproducible entry.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

From d20e03ef10362e709cacc6c580b94ef96b20b6a9 Mon Sep 17 00:00:00 2001
From: Ron Petrusha <ronpet@microsoft.com>
Date: Thu, 26 Sep 2019 14:09:59 -0700
Subject: [PATCH 3/5] Made direct edits.

---
 .../DebugDirectoryEntry.xml                   | 34 +++++++++----------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml
index 128caec0834..74156e5756a 100644
--- a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml
+++ b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntry.xml
@@ -60,7 +60,7 @@
         <param name="dataSize">To be added.</param>
         <param name="dataRelativeVirtualAddress">To be added.</param>
         <param name="dataPointer">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Reflection.PortableExecutable.DebugDirectoryEntry" /> structure.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -84,8 +84,8 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The file pointer to the debug data.</summary>
-        <value>To be added.</value>
+        <summary>Gets the file pointer to the debug data.</summary>
+        <value>The file pointer to the debug data.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -109,8 +109,8 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The address of the debug data when loaded, relative to the image base.</summary>
-        <value>To be added.</value>
+        <summary>Gets the address of the debug data when loaded, relative to the image base.</summary>
+        <value>The address of the debug data relative to the image base.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -134,8 +134,8 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The size of the debug data (not including the debug directory itself).</summary>
-        <value>To be added.</value>
+        <summary>Gets the size of the debug data (not including the debug directory itself).</summary>
+        <value>the size of the debug data (excluding the debug directory).</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -158,8 +158,8 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary><see langword="true" /> if the entry is a <see cref="F:System.Reflection.PortableExecutable.DebugDirectoryEntryType.CodeView" /> entry pointing to a Portable PDB.</summary>
-        <value>To be added.</value>
+        <summary>Gets a value that indicates if the entry is a <see cref="F:System.Reflection.PortableExecutable.DebugDirectoryEntryType.CodeView" /> entry that points to a Portable PDB.</summary>
+        <value><see langword="true" /> if the entry is a <see cref="F:System.Reflection.PortableExecutable.DebugDirectoryEntryType.CodeView" /> entry pointing to a Portable PDB; otherwise, <see langword="false" />.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -183,8 +183,8 @@
         <ReturnType>System.UInt16</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The major version number of the debug data format.</summary>
-        <value>To be added.</value>
+        <summary>Gets the major version number of the debug data format.</summary>
+        <value>The major version number of the debug data format.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -208,8 +208,8 @@
         <ReturnType>System.UInt16</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The minor version number of the debug data format.</summary>
-        <value>To be added.</value>
+        <summary>Gets the minor version number of the debug data format.</summary>
+        <value>The minor version number of the debug data format.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -233,8 +233,8 @@
         <ReturnType>System.UInt32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The time and date that the debug data was created if the PE/COFF file is not deterministic, otherwise a value based on the hash of the content.</summary>
-        <value>To be added.</value>
+        <summary>Get the time and date that the debug data was created if the PE/COFF file is not deterministic; otherwise, gets a value based on the hash of the content.</summary>
+        <value>for a non-deterministic PE/COFF file, the time and date that the debug data was created; otherwise, a value based on the hash of the content.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -266,8 +266,8 @@ The algorithm used to calculate this value is an implementation detail of the to
         <ReturnType>System.Reflection.PortableExecutable.DebugDirectoryEntryType</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The format of debugging information.</summary>
-        <value>To be added.</value>
+        <summary>Gets the format of the debugging information.</summary>
+        <value>The format of the debugging information.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

From 35a54268b38d54a4444455e35d3bea03ae2a29f9 Mon Sep 17 00:00:00 2001
From: Ron Petrusha <ronpet@microsoft.com>
Date: Thu, 26 Sep 2019 14:41:47 -0700
Subject: [PATCH 4/5] Added edits directly

---
 .../DebugDirectoryEntryType.xml               | 86 ++++++-------------
 1 file changed, 28 insertions(+), 58 deletions(-)

diff --git a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
index fadcc70a9d6..4d79669f2a5 100644
--- a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
+++ b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
@@ -18,7 +18,30 @@
   </Base>
   <Docs>
     <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+        <remarks>  
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+See the following for the specifications related to individual enumeration members:
+
+|Member|Specification|
+|---|---|
+|`CodeView`|[CodeView Debug Directory Entry (type 2)](https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#codeview-debug-directory-entry-type-2)|
+|`EmbeddedPortablePdb`|[Embedded Portale PDB Debu Directory Entry (type 17)](https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#embedded-portable-pdb-debug-directory-entry-type-17)|
+|`PdbChecksum`|[PDB Checksum Debug Directory Entry (type 19)](https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#pdb-checksum-debug-directory-entry-type-19)|
+|`Reproducible`|See [Deterministic Debug Directory Entry (type 16)](https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#deterministic-debug-directory-entry-type-16)|
+
+### DebugDirectoryEntryType.Reproducible 
+
+The tool that produced the deterministic PE/COFF file guarantees that the entire content of the file is based solely on documented inputs given to the tool (such as source files, resource files, compiler options, etc.) rather than ambient environment variables (such as the current time, the operating system, the bitness of the process running the tool, etc.).
+
+The value of the `TimeDateStamp` field in the COFF File Header of a deterministic PE/COFF file does not indicate the date and time when the file was produced and should not be interpreted that way. Instead, the value of the field is derived from a hash of the file content. The algorithm to calculate this value is an implementation detail of the tool that produced the file.
+
+The debug directory entry of type <xref:System.Reflection.PortableExecutable.DebugDirectoryEntryType.Reproducible> must have all fields except for <xref:System.Reflection.PortableExecutable.DebugDirectoryEntry.Type?displayProperty=nameWithType> zeroed.
+
+         ]]></format>
+         </remarks>
   </Docs>
   <Members>
     <Member MemberName="CodeView">
@@ -43,15 +66,6 @@
       <MemberValue>2</MemberValue>
       <Docs>
         <summary>Associated PDB file description.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#codeview-debug-directory-entry-type-2 for specification.
-
-          ]]></format>
-        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Coff">
@@ -75,16 +89,7 @@ See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>The COFF debug information (line numbers, symbol table, and string table).</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-This type of debug information is also pointed to by fields in the file headers.
-
-          ]]></format>
-        </remarks>
+        <summary>The COFF debug information (line numbers, symbol table, and string table). This type of debug information is also pointed to by fields in the file headers.</summary>
       </Docs>
     </Member>
     <Member MemberName="EmbeddedPortablePdb">
@@ -107,21 +112,7 @@ This type of debug information is also pointed to by fields in the file headers.
       </ReturnValue>
       <MemberValue>17</MemberValue>
       <Docs>
-        <summary>The entry points to a blob containing Embedded Portable PDB.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-The Embedded Portable PDB blob has the following format:
- 
-  blob ::= uncompressed-size data 
-  Data spans the remainder of the blob and contains a Deflate-compressed Portable PDB.
- 
-See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#embedded-portable-pdb-debug-directory-entry-type-17 for specification.
-
-          ]]></format>
-        </remarks>
+        <summary><para>The entry points to a blob containing Embedded Portable PDB. The Embedded Portable PDB blob has the following format:</para><para>- blob ::= uncompressed-size data</para><para>- Data spans the remainder of the blob and contains a Deflate-compressed Portable PDB.</para></summary>
       </Docs>
     </Member>
     <Member MemberName="PdbChecksum">
@@ -142,20 +133,7 @@ See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/
       </ReturnValue>
       <MemberValue>19</MemberValue>
       <Docs>
-        <summary>The entry stores crypto hash of the content of the symbol file the PE/COFF file was built with.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-The hash can be used to validate that a given PDB file was built with the PE/COFF file and not altered in any way.
-
-More than one entry can be present, in case multiple PDBs were produced during the build of the PE/COFF file (e.g. private and public symbols).
- 
- See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#pdb-checksum-debug-directory-entry-type-19 for specification.
-
-          ]]></format>
-        </remarks>
+        <summary>The entry stores a crypto hash of the content of the symbol file the PE/COFF file was built with. The hash can be used to validate that a given PDB file was built with the PE/COFF file and not altered in any way. More than one entry can be present if multiple PDBs were produced during the build of the PE/COFF file (e.g. private and public symbols).</summary>
       </Docs>
     </Member>
     <Member MemberName="Reproducible">
@@ -179,21 +157,13 @@ More than one entry can be present, in case multiple PDBs were produced during t
       </ReturnValue>
       <MemberValue>16</MemberValue>
       <Docs>
-        <summary>Presence of this entry indicates deterministic PE/COFF file.</summary>
+        <summary>The presence of this entry indicates a deterministic PE/COFF file. See the Remarks section for more information.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-The tool that produced the deterministic PE/COFF file guarantees that the entire content of the file is based solely on documented inputs given to the tool (such as source files, resource files, compiler options, etc.) rather than ambient environment variables (such as the current time, the operating system, the bitness of the process running the tool, etc.).
-
-The value of field `TimeDateStamp` in COFF File Header of a deterministic PE/COFF file does not indicate the date and time when the file was produced and should not be interpreted that way.
-
-Instead the value of the field is derived from a hash of the file content. The algorithm to calculate this value is an implementation detail of the tool that produced the file.
-
-The debug directory entry of type <xref:System.Reflection.PortableExecutable.DebugDirectoryEntryType.Reproducible> must have all fields, except for Type zeroed.
 
-See https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PE-COFF.md#deterministic-debug-directory-entry-type-16 for specification.
  
 
           ]]></format>

From 58d9db2764e816c021b6ca52f9435853ec1c2fbd Mon Sep 17 00:00:00 2001
From: Ron Petrusha <ronpet@microsoft.com>
Date: Fri, 11 Oct 2019 10:23:16 -0700
Subject: [PATCH 5/5] Update DebugDirectoryEntryType.xml

---
 .../DebugDirectoryEntryType.xml                      | 12 +-----------
 1 file changed, 1 insertion(+), 11 deletions(-)

diff --git a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
index 4d79669f2a5..02cc5cd858e 100644
--- a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
+++ b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml
@@ -158,16 +158,6 @@ The debug directory entry of type <xref:System.Reflection.PortableExecutable.Deb
       <MemberValue>16</MemberValue>
       <Docs>
         <summary>The presence of this entry indicates a deterministic PE/COFF file. See the Remarks section for more information.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-
- 
-
-          ]]></format>
-        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Unknown">
@@ -191,7 +181,7 @@ The debug directory entry of type <xref:System.Reflection.PortableExecutable.Deb
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>An unknown value that is ignored by all tools.</summary>
+        <summary>An unknown value that should be ignored by all tools.</summary>
       </Docs>
     </Member>
   </Members>