Add missing docs for System.Reflection.Metadata (#9223)

* Add missing docs for System.Reflection.Metadata * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml --------- Co-authored-by: Genevieve Warren <[email protected]>
dotnet · Aug 29, 2023 · 6c1d2ad · 6c1d2ad
1 parent ed9c008
commit 6c1d2ad
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 29 deletions.
diff --git a/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml b/xml/System.Reflection.Metadata.Ecma335/InstructionEncoder.xml
@@ -895,10 +895,14 @@ 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" /> 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">

diff --git 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
@@ -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>