Backport XML documentation for DynamicILInfo class

src/libraries/System.Reflection.Emit.Lightweight/ref/System.Reflection.Emit.Lightweight.cs

@@ -6,26 +6,173 @@
 
 namespace System.Reflection.Emit
 {
+    /// <summary>
+    /// Provides support for alternative ways to generate the Microsoft intermediate language (MSIL) and metadata for a dynamic method, including methods for creating tokens and for inserting the code, exception handling, and local variable signature blobs.
+    /// </summary>
+    /// <remarks>
+    /// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicilinfo.md">Supplemental API remarks for DynamicILInfo</see>.
+    /// </remarks>
     public sealed partial class DynamicILInfo
     {
         internal DynamicILInfo() { }
+        /// <summary>
+        /// Gets the dynamic method whose body is generated by the current instance.
+        /// </summary>
+        /// <value>A <see cref="T:System.Reflection.Emit.DynamicMethod" /> object representing the dynamic method for which the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object is generating code.</value>
+        /// <remarks>
+        /// A <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object is always associated with a dynamic method. The purpose of the <see cref="T:System.Reflection.Emit.DynamicILInfo" /> class is to provide another way of inserting the MSIL stream, exception handling, and local variable signature into a dynamic method, for developers who want to generate MSIL without using the <see cref="T:System.Reflection.Emit.ILGenerator" /> class.
+        /// </remarks>
         public System.Reflection.Emit.DynamicMethod DynamicMethod { get { throw null; } }
+        /// <summary>
+        /// Gets a token, valid in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" />, representing the signature for the associated dynamic method.
+        /// </summary>
+        /// <param name="signature">An array that contains the signature.</param>
+        /// <returns>A token that can be embedded in the metadata and the MSIL stream for the associated dynamic method.</returns>
+        /// <remarks>
+        /// For information on signature blobs, see the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see <see href="https://www.ecma-international.org/publications-and-standards/standards/ecma-335/">ECMA 335 Common Language Infrastructure (CLI)</see>.
+        /// </remarks>
         public int GetTokenFor(byte[] signature) { throw null; }
+        /// <summary>
+        /// Gets a token, valid in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" />, representing a dynamic method to be called from the associated method.
+        /// </summary>
+        /// <param name="method">The dynamic method to call.</param>
+        /// <returns>A token that can be embedded in the MSIL stream for the associated dynamic method, as the target of an MSIL instruction.</returns>
+        /// <remarks>
+        /// The token returned by this method overload allows you to call a dynamic method from the dynamic method associated with the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object. To call the associated dynamic method recursively, pass the value of the <see cref="P:System.Reflection.Emit.DynamicILInfo.DynamicMethod" /> property.
+        /// </remarks>
         public int GetTokenFor(System.Reflection.Emit.DynamicMethod method) { throw null; }
+        /// <summary>
+        /// Gets a token, valid in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" />, representing a field to be accessed from the associated dynamic method.
+        /// </summary>
+        /// <param name="field">The field to be accessed.</param>
+        /// <returns>A token that can be used as the operand of an MSIL instruction that accesses fields, in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object.</returns>
+        /// <remarks>
+        /// You must obtain a token for any field that will be accessed by the dynamic method associated with the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object. Use the <see cref="M:System.Type.GetField(System.String)">Type.GetField</see> method to get a <see cref="T:System.Reflection.FieldInfo" /> for the field you want to access, then use the <see cref="P:System.Reflection.FieldInfo.FieldHandle" /> property to get the <see cref="T:System.RuntimeFieldHandle" />.
+        /// </remarks>
         public int GetTokenFor(System.RuntimeFieldHandle field) { throw null; }
+        /// <summary>
+        /// Gets a token, valid in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" />, representing a field to be accessed from the associated dynamic method; the field is on the specified generic type.
+        /// </summary>
+        /// <param name="field">The field to be accessed.</param>
+        /// <param name="contextType">The generic type the field belongs to.</param>
+        /// <returns>A token that can be used as the operand of an MSIL instruction that accesses fields in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object.</returns>
+        /// <remarks>
+        /// You must obtain a token for any field that will be accessed by the dynamic method associated with the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object. Use the <see cref="M:System.Type.GetField(System.String)">Type.GetField</see> method to get a <see cref="T:System.Reflection.FieldInfo" /> for the field you want to access, and then use the <see cref="P:System.Reflection.FieldInfo.FieldHandle" /> property to get the <see cref="T:System.RuntimeFieldHandle" />.
+        /// </remarks>
         public int GetTokenFor(System.RuntimeFieldHandle field, System.RuntimeTypeHandle contextType) { throw null; }
+        /// <summary>
+        /// Gets a token, valid in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" />, representing a method to be accessed from the associated dynamic method.
+        /// </summary>
+        /// <param name="method">The method to be accessed.</param>
+        /// <returns>A token that can be used as the operand of an MSIL instruction that accesses methods, such as <see cref="F:System.Reflection.Emit.OpCodes.Call" /> or <see cref="F:System.Reflection.Emit.OpCodes.Ldtoken" />, in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object.</returns>
+        /// <remarks>
+        /// You must obtain a token for any method that will be accessed by the dynamic method associated with the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object. Use the <see cref="M:System.Type.GetMethod(System.String)">Type.GetMethod</see> method to get a <see cref="T:System.Reflection.MethodInfo" /> for the method you want to access, and then use the <see cref="P:System.Reflection.MethodBase.MethodHandle" /> property to get the <see cref="T:System.RuntimeMethodHandle" />.
+        /// 
+        /// <note>
+        /// For a method that belongs to a generic type, use the <see cref="M:System.Reflection.Emit.DynamicILInfo.GetTokenFor(System.RuntimeMethodHandle,System.RuntimeTypeHandle)" /> method overload and specify a <see cref="T:System.RuntimeTypeHandle" /> for the generic type.
+        /// </note>
+        /// </remarks>
         public int GetTokenFor(System.RuntimeMethodHandle method) { throw null; }
+        /// <summary>
+        /// Gets a token, valid in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" />, representing a method on a generic type.
+        /// </summary>
+        /// <param name="method">The method.</param>
+        /// <param name="contextType">The generic type the method belongs to.</param>
+        /// <returns>A token that can be used as the operand of an MSIL instruction that accesses methods, such as <see cref="F:System.Reflection.Emit.OpCodes.Call" /> or <see cref="F:System.Reflection.Emit.OpCodes.Ldtoken" />, in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object.</returns>
+        /// <remarks>
+        /// You must obtain a token for any method that will be called by the dynamic method associated with the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object. Use the <see cref="M:System.Type.GetMethod(System.String)">Type.GetMethod</see> method to get a <see cref="T:System.Reflection.MethodInfo" /> for the method you want to call, and then use the <see cref="P:System.Reflection.MethodBase.MethodHandle" /> property to get the <see cref="T:System.RuntimeMethodHandle" />.
+        /// </remarks>
         public int GetTokenFor(System.RuntimeMethodHandle method, System.RuntimeTypeHandle contextType) { throw null; }
+        /// <summary>
+        /// Gets a token, valid in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" />, representing a type to be used in the associated dynamic method.
+        /// </summary>
+        /// <param name="type">The type to be used.</param>
+        /// <returns>A token that can be used as the operand of an MSIL instruction that requires a type, in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object.</returns>
+        /// <remarks>
+        /// The token returned by this method overload allows you to define a local variable type, and emit MSIL to create an instance of a type in the dynamic method associated with the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object.
+        /// 
+        /// To get a <see cref="T:System.RuntimeTypeHandle" /> representing a type, use the <see cref="P:System.Type.TypeHandle" /> property.
+        /// </remarks>
         public int GetTokenFor(System.RuntimeTypeHandle type) { throw null; }
+        /// <summary>
+        /// Gets a token, valid in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" />, representing a string literal to be used in the associated dynamic method.
+        /// </summary>
+        /// <param name="literal">The string to be used.</param>
+        /// <returns>A token that can be used as the operand of an MSIL instruction that requires a string, in the scope of the current <see cref="T:System.Reflection.Emit.DynamicILInfo" /> object.</returns>
         public int GetTokenFor(string literal) { throw null; }
         [System.CLSCompliantAttribute(false)]
+        /// <summary>
+        /// Sets the code body of the associated dynamic method.
+        /// </summary>
+        /// <param name="code">A pointer to a byte array containing the MSIL stream.</param>
+        /// <param name="codeSize">The number of bytes in the MSIL stream.</param>
+        /// <param name="maxStackSize">The maximum number of items on the operand stack when the method is executing.</param>
+        /// <remarks>
+        /// No validity checks are performed on the MSIL stream.
+        /// 
+        /// Calling this method a second time replaces the first MSIL stream with the second.
+        /// 
+        /// Generating your own metadata and MSIL requires familiarity with the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics" and "Partition III: CIL Instruction Set." For more information, see <see href="https://www.ecma-international.org/publications-and-standards/standards/ecma-335/">ECMA 335 Common Language Infrastructure (CLI)</see>.
+        /// </remarks>
+        /// <exception cref="T:System.ArgumentNullException"><paramref name="code" /> is <see langword="null" /> and <paramref name="codeSize" /> is greater than 0.</exception>
+        /// <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="codeSize" /> is less than 0.</exception>
         public unsafe void SetCode(byte* code, int codeSize, int maxStackSize) { }
+        /// <summary>
+        /// Sets the code body of the associated dynamic method.
+        /// </summary>
+        /// <param name="code">An array that contains the MSIL stream.</param>
+        /// <param name="maxStackSize">The maximum number of items on the operand stack when the method is executing.</param>
+        /// <remarks>
+        /// No validity checks are performed on the MSIL stream.
+        /// 
+        /// Calling this method a second time replaces the first MSIL stream with the second.
+        /// 
+        /// Generating your own metadata and MSIL requires familiarity with the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics" and "Partition III: CIL Instruction Set". For more information, see <see href="https://www.ecma-international.org/publications-and-standards/standards/ecma-335/">ECMA 335 Common Language Infrastructure (CLI)</see>.
+        /// </remarks>
         public void SetCode(byte[]? code, int maxStackSize) { }
         [System.CLSCompliantAttribute(false)]
+        /// <summary>
+        /// Sets the exception metadata for the associated dynamic method.
+        /// </summary>
+        /// <param name="exceptions">A pointer to a byte array containing the exception metadata.</param>
+        /// <param name="exceptionsSize">The number of bytes of exception metadata.</param>
+        /// <remarks>
+        /// The exception metadata for a method defines the location and size of all `try`, `catch`, `finally`, filter, and fault blocks. For information on the layout of this metadata, see the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics" and "Partition III: CIL Instruction Set". For more information, see <see href="https://www.ecma-international.org/publications-and-standards/standards/ecma-335/">ECMA 335 Common Language Infrastructure (CLI)</see>.
+        /// </remarks>
+        /// <exception cref="T:System.ArgumentNullException"><paramref name="exceptions" /> is <see langword="null" /> and <paramref name="exceptionsSize" /> is greater than 0.</exception>
+        /// <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="exceptionsSize" /> is less than 0.</exception>
         public unsafe void SetExceptions(byte* exceptions, int exceptionsSize) { }
+        /// <summary>
+        /// Sets the exception metadata for the associated dynamic method.
+        /// </summary>
+        /// <param name="exceptions">An array that contains the exception metadata.</param>
+        /// <remarks>
+        /// The exception metadata for a method defines the location and size of all `try`, `catch`, `finally`, filter, and fault blocks. For information on the layout of this metadata, see the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see <see href="https://www.ecma-international.org/publications-and-standards/standards/ecma-335/">ECMA 335 Common Language Infrastructure (CLI)</see>.
+        /// </remarks>
         public void SetExceptions(byte[]? exceptions) { }
         [System.CLSCompliantAttribute(false)]
+        /// <summary>
+        /// Sets the local variable signature that describes the layout of local variables for the associated dynamic method.
+        /// </summary>
+        /// <param name="localSignature">An array that contains the layout of local variables for the associated <see cref="T:System.Reflection.Emit.DynamicMethod" />.</param>
+        /// <param name="signatureSize">The number of bytes in the signature.</param>
+        /// <remarks>
+        /// The local variable signature describes the layout of a method's local variables. To simplify construction of the local variable signature, use the <see langword="static" /> (<see langword="Shared" /> in Visual Basic) <see cref="M:System.Reflection.Emit.SignatureHelper.GetLocalVarSigHelper">SignatureHelper.GetLocalVarSigHelper</see> method to get a <see cref="T:System.Reflection.Emit.SignatureHelper" /> for the local signature.
+        /// 
+        /// For information on local variable signatures, see the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see <see href="https://www.ecma-international.org/publications-and-standards/standards/ecma-335/">ECMA 335 Common Language Infrastructure (CLI)</see>.
+        /// </remarks>
+        /// <exception cref="T:System.ArgumentNullException"><paramref name="localSignature" /> is <see langword="null" /> and <paramref name="signatureSize" /> is greater than 0.</exception>
+        /// <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="signatureSize" /> is less than 0.</exception>
         public unsafe void SetLocalSignature(byte* localSignature, int signatureSize) { }
+        /// <summary>
+        /// Sets the local variable signature that describes the layout of local variables for the associated dynamic method.
+        /// </summary>
+        /// <param name="localSignature">An array that contains the layout of local variables for the associated <see cref="T:System.Reflection.Emit.DynamicMethod" />.</param>
+        /// <remarks>
+        /// The local variable signature describes the layout of a method's local variables. To simplify construction of the local variable signature, use the <see langword="static" /> (<see langword="Shared" /> in Visual Basic) <see cref="M:System.Reflection.Emit.SignatureHelper.GetLocalVarSigHelper">SignatureHelper.GetLocalVarSigHelper</see> method to get a <see cref="T:System.Reflection.Emit.SignatureHelper" /> for the local signature.
+        /// 
+        /// For information on local variable signatures, see the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see <see href="https://www.ecma-international.org/publications-and-standards/standards/ecma-335/">ECMA 335 Common Language Infrastructure (CLI)</see>.
+        /// </remarks>
         public void SetLocalSignature(byte[]? localSignature) { }
     }
     public sealed partial class DynamicMethod : System.Reflection.MethodInfo