From 18066352a0053d3c3093283775f7c049496796f4 Mon Sep 17 00:00:00 2001
From: Buyaa Namnan <bunamnan@microsoft.com>
Date: Mon, 28 Aug 2023 21:58:30 -0700
Subject: [PATCH 1/3] Add missing docs for System.Reflection.Metadata

---
 .../InstructionEncoder.xml                    | 11 +++--
 .../SignatureTypeEncoder.xml                  | 42 +++++++++----------
 .../SwitchInstructionEncoder.xml              |  8 ++--
 3 files changed, 32 insertions(+), 29 deletions(-)

diff --git a/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml b/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
index d211f740bf2..db207c6764f 100644
--- a/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
+++ b/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
@@ -895,10 +895,13 @@ A single label may be marked multiple times, the last offset wins.
         <Parameter Name="branchCount" Type="System.Int32" Index="0" FrameworkAlternate="net-8.0" />
       </Parameters>
       <Docs>
-        <param name="branchCount">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="branchCount">The number of branches the instruction will have.</param>
+        <summary>Starts encoding a switch instruction.</summary>
+        <returns>A <see cref="T:System.Reflection.Metadata.Ecma335.SwitchInstructionEncoder" /> that will be used to emit the labels for the branches.</returns>
+        <remarks>Before using this <see cref="T:System.Reflection.Metadata.Ecma335.InstructionEncoder" /> in any other way, the method <see cref="M:System.Reflection.Metadata.Ecma335.SwitchInstructionEncoder.Branch(System.Reflection.Metadata.Ecma335.LabelHandle)" /> must be called on the returned value exactly <paramref name="branchCount" /> times. Failure to do so will throw <see cref="T:System.InvalidOperationException" />.</remarks>
+        <exception cref="T:System.ArgumentOutOfRangeException">
+          <paramref name="branchCount" />
+            less than or equal to zero.</exception>
       </Docs>
     </Member>
     <Member MemberName="Token">
diff --git a/xml/System.Reflection.Metadata.Ecma335/SignatureTypeEncoder.xml b/xml/System.Reflection.Metadata.Ecma335/SignatureTypeEncoder.xml
index ba421bc29cc..7f9908d3025 100644
--- a/xml/System.Reflection.Metadata.Ecma335/SignatureTypeEncoder.xml
+++ b/xml/System.Reflection.Metadata.Ecma335/SignatureTypeEncoder.xml
@@ -37,7 +37,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Encodes a type in a signature.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -65,8 +65,8 @@
         <Parameter Name="builder" Type="System.Reflection.Metadata.BlobBuilder" />
       </Parameters>
       <Docs>
-        <param name="builder">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="builder">The <see cref="T:System.Reflection.Metadata.BlobBuilder" /> where the signature will be written.</param>
+        <summary>Creates a <see cref="T:System.Reflection.Metadata.Ecma335.SignatureTypeEncoder" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -165,7 +165,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.Boolean" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -193,7 +193,7 @@
         <ReturnType>System.Reflection.Metadata.BlobBuilder</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The <see cref="T:System.Reflection.Metadata.BlobBuilder" /> where the signature is written to.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -223,7 +223,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.Byte" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -252,7 +252,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.Char" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -311,7 +311,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.Double" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -491,7 +491,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.Int16" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -520,7 +520,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.Int32" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -549,7 +549,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.Int64" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -578,7 +578,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.IntPtr" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -607,7 +607,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.Object" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -700,7 +700,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.SByte" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -729,7 +729,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.Single" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -758,7 +758,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.String" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -847,7 +847,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.TypedReference" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -876,7 +876,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.UInt16" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -905,7 +905,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.UInt32" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -934,7 +934,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.UInt64" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -963,7 +963,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Encodes <see cref="T:System.UIntPtr" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
diff --git a/xml/System.Reflection.Metadata.Ecma335/SwitchInstructionEncoder.xml b/xml/System.Reflection.Metadata.Ecma335/SwitchInstructionEncoder.xml
index 66912df2afe..339486b160a 100644
--- a/xml/System.Reflection.Metadata.Ecma335/SwitchInstructionEncoder.xml
+++ b/xml/System.Reflection.Metadata.Ecma335/SwitchInstructionEncoder.xml
@@ -20,8 +20,8 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Encodes the branches of an IL <c>switch</c> instruction.</summary>
+    <remarks>See <see cref="M:System.Reflection.Metadata.Ecma335.InstructionEncoder.Switch(System.Int32)" /> for usage guidelines.</remarks>
   </Docs>
   <Members>
     <Member MemberName="Branch">
@@ -44,8 +44,8 @@
       </Parameters>
       <Docs>
         <param name="label">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <summary>Encodes a branch that is part of a switch instruction.</summary>
+        <remarks>See <see cref="M:System.Reflection.Metadata.Ecma335.InstructionEncoder.Switch(System.Int32)" /> for usage guidelines.</remarks>
       </Docs>
     </Member>
   </Members>

From 404956bd68acd329b2f0061e511b49f16f7811d9 Mon Sep 17 00:00:00 2001
From: Buyaa Namnan <buyankhishig.namnan@microsoft.com>
Date: Tue, 29 Aug 2023 14:23:00 -0700
Subject: [PATCH 2/3] Apply suggestions from code review

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
---
 .../InstructionEncoder.xml                                   | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml b/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
index db207c6764f..bf86076189f 100644
--- a/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
+++ b/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
@@ -900,8 +900,9 @@ A single label may be marked multiple times, the last offset wins.
         <returns>A <see cref="T:System.Reflection.Metadata.Ecma335.SwitchInstructionEncoder" /> that will be used to emit the labels for the branches.</returns>
         <remarks>Before using this <see cref="T:System.Reflection.Metadata.Ecma335.InstructionEncoder" /> in any other way, the method <see cref="M:System.Reflection.Metadata.Ecma335.SwitchInstructionEncoder.Branch(System.Reflection.Metadata.Ecma335.LabelHandle)" /> must be called on the returned value exactly <paramref name="branchCount" /> times. Failure to do so will throw <see cref="T:System.InvalidOperationException" />.</remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="branchCount" />
-            less than or equal to zero.</exception>
+          <paramref name="branchCount" /> is less than or equal to zero.</exception>
+            <exception cref="T:System.InvalidOperationException">
+              <see cref="M:System.Reflection.Metadata.Ecma335.SwitchInstructionEncoder.Branch(System.Reflection.Metadata.Ecma335.LabelHandle)" /> was not called on the returned value exactly <paramref name="branchCount" /> times.</exception>
       </Docs>
     </Member>
     <Member MemberName="Token">

From 159257e870dfc0defe3b4558c90ad4db9ab61505 Mon Sep 17 00:00:00 2001
From: Buyaa Namnan <buyankhishig.namnan@microsoft.com>
Date: Tue, 29 Aug 2023 14:24:18 -0700
Subject: [PATCH 3/3] Update
 xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml

---
 xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml b/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
index bf86076189f..6fe85e5317d 100644
--- a/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
+++ b/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
@@ -901,8 +901,8 @@ A single label may be marked multiple times, the last offset wins.
         <remarks>Before using this <see cref="T:System.Reflection.Metadata.Ecma335.InstructionEncoder" /> in any other way, the method <see cref="M:System.Reflection.Metadata.Ecma335.SwitchInstructionEncoder.Branch(System.Reflection.Metadata.Ecma335.LabelHandle)" /> must be called on the returned value exactly <paramref name="branchCount" /> times. Failure to do so will throw <see cref="T:System.InvalidOperationException" />.</remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="branchCount" /> is less than or equal to zero.</exception>
-            <exception cref="T:System.InvalidOperationException">
-              <see cref="M:System.Reflection.Metadata.Ecma335.SwitchInstructionEncoder.Branch(System.Reflection.Metadata.Ecma335.LabelHandle)" /> was not called on the returned value exactly <paramref name="branchCount" /> times.</exception>
+        <exception cref="T:System.InvalidOperationException">
+          <see cref="M:System.Reflection.Metadata.Ecma335.SwitchInstructionEncoder.Branch(System.Reflection.Metadata.Ecma335.LabelHandle)" /> was not called on the returned value exactly <paramref name="branchCount" /> times.</exception>
       </Docs>
     </Member>
     <Member MemberName="Token">