Skip to content

Commit 2f4fe14

Browse files
Copilotgewarren
Copilot
and
gewarren
committed
Address review feedback: add missing remarks and fix supplemental links
Co-authored-by: gewarren <[email protected]>
1 parent f1fa223 commit 2f4fe14

File tree

2 files changed

+85
-9
lines changed

2 files changed

+85
-9
lines changed

‎src/coreclr/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.CoreCLR.cs‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ public sealed partial class DynamicMethod : MethodInfo
4949
/// <exception cref="InvalidOperationException">The dynamic method has no method body.</exception>
5050
/// <exception cref="ArgumentException"><paramref name="delegateType" /> has the wrong number of parameters or the wrong parameter types.</exception>
5151
/// <remarks>
52-
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod.md">Supplemental API remarks for DynamicMethod</see>.
52+
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-createdelegate.md">Supplemental API remarks for DynamicMethod.CreateDelegate</see>.
5353
/// </remarks>
5454
public sealed override Delegate CreateDelegate(Type delegateType) =>
5555
CreateDelegate(delegateType, target: null);
@@ -63,7 +63,7 @@ public sealed override Delegate CreateDelegate(Type delegateType) =>
6363
/// <exception cref="InvalidOperationException">The dynamic method has no method body.</exception>
6464
/// <exception cref="ArgumentException"><paramref name="delegateType" /> has the wrong number of parameters or the wrong parameter types.</exception>
6565
/// <remarks>
66-
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod.md">Supplemental API remarks for DynamicMethod</see>.
66+
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-createdelegate.md">Supplemental API remarks for DynamicMethod.CreateDelegate</see>.
6767
/// </remarks>
6868
public sealed override Delegate CreateDelegate(Type delegateType, object? target)
6969
{
@@ -148,7 +148,7 @@ Signature LazyCreateSignature()
148148
/// <exception cref="NotSupportedException">The dynamic method contains unverifiable code.</exception>
149149
/// <exception cref="InvalidOperationException">The dynamic method has no method body.</exception>
150150
/// <remarks>
151-
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod.md">Supplemental API remarks for DynamicMethod</see>.
151+
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-invoke.md">Supplemental API remarks for DynamicMethod.Invoke</see>.
152152
/// </remarks>
153153
public override object? Invoke(object? obj, BindingFlags invokeAttr, Binder? binder, object?[]? parameters, CultureInfo? culture)
154154
{
@@ -183,6 +183,9 @@ Signature LazyCreateSignature()
183183
/// Returns a <see cref="DynamicILInfo" /> object that can be used to generate a method body from metadata tokens, scopes, and Microsoft intermediate language (MSIL) streams.
184184
/// </summary>
185185
/// <returns>A <see cref="DynamicILInfo" /> object that can be used to generate a method body from metadata tokens, scopes, and MSIL streams.</returns>
186+
/// <remarks>
187+
/// The <see cref="DynamicILInfo" /> class is provided to support unmanaged code generation.
188+
/// </remarks>
186189
public DynamicILInfo GetDynamicILInfo()
187190
{
188191
if (_dynamicILInfo == null)
@@ -200,7 +203,7 @@ public DynamicILInfo GetDynamicILInfo()
200203
/// <param name="streamSize">The size of the MSIL stream, in bytes.</param>
201204
/// <returns>An <see cref="ILGenerator" /> object for the method.</returns>
202205
/// <remarks>
203-
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod.md">Supplemental API remarks for DynamicMethod</see>.
206+
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-getilgenerator.md">Supplemental API remarks for DynamicMethod.GetILGenerator</see>.
204207
/// </remarks>
205208
public ILGenerator GetILGenerator(int streamSize)
206209
{

‎src/libraries/System.Private.CoreLib/src/System/Reflection/Emit/DynamicMethod.cs‎

Lines changed: 78 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -450,6 +450,9 @@ private void Init(string name,
450450
/// Returns a string representation of the dynamic method.
451451
/// </summary>
452452
/// <returns>A string representation of the dynamic method, showing the return type, name, and parameter types.</returns>
453+
/// <remarks>
454+
/// The signature includes only types and the method name, if any. Parameter names are not included.
455+
/// </remarks>
453456
public override string ToString()
454457
{
455458
var sbName = new ValueStringBuilder(MethodNameBufferSize);
@@ -469,24 +472,36 @@ public override string ToString()
469472
/// Gets the name of the dynamic method.
470473
/// </summary>
471474
/// <value>The name of the dynamic method.</value>
475+
/// <remarks>
476+
/// <note type="note">It is not necessary to name dynamic methods.</note>
477+
/// </remarks>
472478
public override string Name => _name;
473479

474480
/// <summary>
475481
/// Gets the type that declares the dynamic method.
476482
/// </summary>
477483
/// <value>Always <see langword="null" /> for dynamic methods.</value>
484+
/// <remarks>
485+
/// This property always returns <see langword="null" /> for dynamic methods. Even when a dynamic method is logically associated with a type, it is not declared by the type.
486+
/// </remarks>
478487
public override Type? DeclaringType => null;
479488

480489
/// <summary>
481490
/// Gets the class object that was used to obtain the instance of the dynamic method.
482491
/// </summary>
483492
/// <value>Always <see langword="null" /> for dynamic methods.</value>
493+
/// <remarks>
494+
/// This property always returns <see langword="null" /> for dynamic methods.
495+
/// </remarks>
484496
public override Type? ReflectedType => null;
485497

486498
/// <summary>
487499
/// Gets the module associated with the dynamic method.
488500
/// </summary>
489501
/// <value>The <see cref="System.Reflection.Module" /> associated with the dynamic method.</value>
502+
/// <remarks>
503+
/// If a module was specified when the dynamic method was created, this property returns that module. If a type was specified as the owner when the dynamic method was created, this property returns the module that contains that type.
504+
/// </remarks>
490505
public override Module Module => _module;
491506

492507
// we cannot return a MethodHandle because we cannot track it via GC so this method is off limits
@@ -501,24 +516,36 @@ public override string ToString()
501516
/// Gets the attributes specified when the dynamic method was created.
502517
/// </summary>
503518
/// <value>A bitwise combination of the <see cref="MethodAttributes" /> values representing the attributes for the method.</value>
519+
/// <remarks>
520+
/// Currently, the method attributes for a dynamic method are always <see cref="MethodAttributes.Public" /> and <see cref="MethodAttributes.Static" />.
521+
/// </remarks>
504522
public override MethodAttributes Attributes => _attributes;
505523

506524
/// <summary>
507525
/// Gets the calling convention specified when the dynamic method was created.
508526
/// </summary>
509527
/// <value>One of the <see cref="CallingConventions" /> values that indicates the calling convention of the method.</value>
528+
/// <remarks>
529+
/// Currently, the calling convention for a dynamic method is always <see cref="CallingConventions.Standard" />.
530+
/// </remarks>
510531
public override CallingConventions CallingConvention => _callingConvention;
511532

512533
/// <summary>
513534
/// Returns the base definition for the dynamic method.
514535
/// </summary>
515536
/// <returns>Always returns this dynamic method.</returns>
537+
/// <remarks>
538+
/// This method always returns the current <see cref="DynamicMethod" /> object.
539+
/// </remarks>
516540
public override MethodInfo GetBaseDefinition() => this;
517541

518542
/// <summary>
519543
/// Returns an array of <see cref="ParameterInfo" /> objects representing the parameters of the dynamic method.
520544
/// </summary>
521545
/// <returns>An array of <see cref="ParameterInfo" /> objects representing the parameters of the dynamic method, or an empty array if the method has no parameters.</returns>
546+
/// <remarks>
547+
/// The <see cref="ParameterInfo" /> objects returned by this method are for information only. Use the <see cref="DefineParameter" /> method to set or change the characteristics of the parameters.
548+
/// </remarks>
522549
public override ParameterInfo[] GetParameters() =>
523550
GetParametersAsSpan().ToArray();
524551

@@ -528,28 +555,46 @@ public override ParameterInfo[] GetParameters() =>
528555
/// Returns the implementation flags for the method.
529556
/// </summary>
530557
/// <returns>A bitwise combination of <see cref="MethodImplAttributes" /> values representing the implementation flags for the method.</returns>
558+
/// <remarks>
559+
/// Currently, method implementation attributes for dynamic methods are always <see cref="MethodImplAttributes.IL" /> and <see cref="MethodImplAttributes.NoInlining" />.
560+
/// </remarks>
531561
public override MethodImplAttributes GetMethodImplementationFlags() =>
532562
MethodImplAttributes.IL | MethodImplAttributes.NoInlining;
533563

534564
/// <summary>
535565
/// Gets a value that indicates whether the dynamic method is security-critical.
536566
/// </summary>
537-
/// <value><see langword="true" /> for all dynamic methods.</value>
567+
/// <value>
568+
/// .NET (Core): <see langword="true" /> for all dynamic methods.
569+
/// .NET Framework: <see langword="true" /> if the current dynamic method is security-critical or security-safe-critical; <see langword="false" /> if it is transparent.
570+
/// </value>
538571
/// <remarks>
539-
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod.md">Supplemental API remarks for DynamicMethod</see>.
572+
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-issecuritycritical.md">Supplemental API remarks for DynamicMethod.IsSecurityCritical</see>.
540573
/// </remarks>
541574
public override bool IsSecurityCritical => true;
542575

543576
/// <summary>
544577
/// Gets a value that indicates whether the dynamic method is security-safe-critical.
545578
/// </summary>
546-
/// <value><see langword="false" /> for all dynamic methods.</value>
579+
/// <value>
580+
/// .NET (Core): <see langword="false" /> for all dynamic methods.
581+
/// .NET Framework: <see langword="true" /> if the dynamic method is safe-critical; <see langword="false" /> if it is critical or transparent.
582+
/// </value>
583+
/// <remarks>
584+
/// <note type="note">For .NET Framework remarks about security transparency, see the <see cref="IsSecurityCritical" /> property.</note>
585+
/// </remarks>
547586
public override bool IsSecuritySafeCritical => false;
548587

549588
/// <summary>
550589
/// Gets a value that indicates whether the dynamic method is security-transparent.
551590
/// </summary>
552-
/// <value><see langword="false" /> for all dynamic methods.</value>
591+
/// <value>
592+
/// .NET (Core): <see langword="false" /> for all dynamic methods.
593+
/// .NET Framework: <see langword="true" /> if the dynamic method is transparent; otherwise, <see langword="false" />.
594+
/// </value>
595+
/// <remarks>
596+
/// <note type="note">For .NET Framework remarks about security transparency, see the <see cref="IsSecurityCritical" /> property.</note>
597+
/// </remarks>
553598
public override bool IsSecurityTransparent => false;
554599

555600
/// <summary>
@@ -560,6 +605,10 @@ public override MethodImplAttributes GetMethodImplementationFlags() =>
560605
/// <returns>An array of custom attributes defined on the dynamic method. If no attributes of the specified type are defined, an empty array is returned.</returns>
561606
/// <exception cref="ArgumentException"><paramref name="attributeType" /> is not a <see cref="RuntimeType" />.</exception>
562607
/// <exception cref="ArgumentNullException"><paramref name="attributeType" /> is <see langword="null" />.</exception>
608+
/// <remarks>
609+
/// For dynamic methods, specifying <see langword="true" /> for <paramref name="inherit" /> has no effect, because the method is not declared in a type.
610+
/// <note type="note">Custom attributes are not currently supported on dynamic methods. The only attribute returned is <see cref="System.Runtime.CompilerServices.MethodImplAttribute" />; you can get the method implementation flags more easily using the <see cref="GetMethodImplementationFlags" /> method.</note>
611+
/// </remarks>
563612
public override object[] GetCustomAttributes(Type attributeType, bool inherit)
564613
{
565614
ArgumentNullException.ThrowIfNull(attributeType);
@@ -581,6 +630,10 @@ public override object[] GetCustomAttributes(Type attributeType, bool inherit)
581630
/// </summary>
582631
/// <param name="inherit">This parameter is ignored for dynamic methods, because they do not support inheritance.</param>
583632
/// <returns>An array of all custom attributes defined on the dynamic method.</returns>
633+
/// <remarks>
634+
/// For dynamic methods, specifying <see langword="true" /> for <paramref name="inherit" /> has no effect, because the method is not declared in a type.
635+
/// <note type="note">Custom attributes are not currently supported on dynamic methods. The only attribute returned is <see cref="System.Runtime.CompilerServices.MethodImplAttribute" />; you can get the method implementation flags more easily using the <see cref="GetMethodImplementationFlags" /> method.</note>
636+
/// </remarks>
584637
public override object[] GetCustomAttributes(bool inherit)
585638
{
586639
// support for MethodImplAttribute PCA
@@ -594,6 +647,10 @@ public override object[] GetCustomAttributes(bool inherit)
594647
/// <param name="inherit">This parameter is ignored for dynamic methods, because they do not support inheritance.</param>
595648
/// <returns><see langword="true" /> if one or more instances of <paramref name="attributeType" /> or any of its derived types is applied to this method; otherwise, <see langword="false" />.</returns>
596649
/// <exception cref="ArgumentNullException"><paramref name="attributeType" /> is <see langword="null" />.</exception>
650+
/// <remarks>
651+
/// For dynamic methods, specifying <see langword="true" /> for <paramref name="inherit" /> has no effect. Dynamic methods have no inheritance chain.
652+
/// <note type="note">Custom attributes are not currently supported on dynamic methods.</note>
653+
/// </remarks>
597654
public override bool IsDefined(Type attributeType, bool inherit)
598655
{
599656
ArgumentNullException.ThrowIfNull(attributeType);
@@ -605,18 +662,27 @@ public override bool IsDefined(Type attributeType, bool inherit)
605662
/// Gets the return type of the dynamic method.
606663
/// </summary>
607664
/// <value>A <see cref="Type" /> representing the return type of the dynamic method; or <see cref="void" /> if the method has no return type.</value>
665+
/// <remarks>
666+
/// If <see langword="null" /> was specified for the return type when the dynamic method was created, this property returns <see cref="void" />.
667+
/// </remarks>
608668
public override Type ReturnType => _returnType;
609669

610670
/// <summary>
611671
/// Gets the return parameter of the dynamic method.
612672
/// </summary>
613673
/// <value>A <see cref="ParameterInfo" /> object that represents the return parameter of the dynamic method.</value>
674+
/// <remarks>
675+
/// This property always returns <see langword="null" /> for dynamic methods.
676+
/// </remarks>
614677
public override ParameterInfo ReturnParameter => new RuntimeParameterInfo(this, null, _returnType, -1);
615678

616679
/// <summary>
617680
/// Gets the custom attributes of the return type for the dynamic method.
618681
/// </summary>
619682
/// <value>An <see cref="ICustomAttributeProvider" /> representing the custom attributes of the return type for the dynamic method.</value>
683+
/// <remarks>
684+
/// Custom attributes are not supported on the return type of a dynamic method, so the array of custom attributes returned by the <see cref="ICustomAttributeProvider.GetCustomAttributes(bool)" /> method is always empty.
685+
/// </remarks>
620686
public override ICustomAttributeProvider ReturnTypeCustomAttributes => new EmptyCAHolder();
621687

622688
//
@@ -635,6 +701,10 @@ public override bool IsDefined(Type attributeType, bool inherit)
635701
/// <paramref name="position" /> is less than 0.
636702
/// -or-
637703
/// <paramref name="position" /> is greater than the number of parameters of the dynamic method.</exception>
704+
/// <remarks>
705+
/// If <paramref name="position" /> is 0, the <see cref="DefineParameter" /> method refers to the return value. Setting parameter information has no effect on the return value.
706+
/// <para>If the dynamic method has already been completed, by calling the <see cref="CreateDelegate(Type)" /> or <see cref="Invoke" /> method, the <see cref="DefineParameter" /> method has no effect. No exception is thrown.</para>
707+
/// </remarks>
638708
public ParameterBuilder? DefineParameter(int position, ParameterAttributes attributes, string? parameterName)
639709
{
640710
if (position < 0 || position > _parameterTypes.Length)
@@ -655,7 +725,7 @@ public override bool IsDefined(Type attributeType, bool inherit)
655725
/// </summary>
656726
/// <returns>An <see cref="ILGenerator" /> object for the method.</returns>
657727
/// <remarks>
658-
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod.md">Supplemental API remarks for DynamicMethod</see>.
728+
/// For more information about this API, see <see href="https://raw.githubusercontent.com/dotnet/docs/main/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-getilgenerator.md">Supplemental API remarks for DynamicMethod.GetILGenerator</see>.
659729
/// </remarks>
660730
public ILGenerator GetILGenerator()
661731
{
@@ -666,6 +736,9 @@ public ILGenerator GetILGenerator()
666736
/// Gets or sets a value indicating whether the local variables in the method are zero-initialized.
667737
/// </summary>
668738
/// <value><see langword="true" /> if the local variables in the method are zero-initialized; otherwise, <see langword="false" />. The default is <see langword="true" />.</value>
739+
/// <remarks>
740+
/// If this property is set to <see langword="true" />, the emitted Microsoft intermediate language (MSIL) includes initialization of local variables. If it is set to <see langword="false" />, local variables are not initialized and the generated code is unverifiable.
741+
/// </remarks>
669742
public bool InitLocals
670743
{
671744
get => _initLocals;

0 commit comments

Comments
 (0)