[release/8.0] Add doc for the new invoker classes (#90636)

* Add doc new invoker classes

* Fix cref typo

* Misc errors

* Remove arg reference in 0-arg ctor summary

---------

Co-authored-by: Steve Harter <steveharter@users.noreply.github.com>

diff --git a/src/libraries/System.Private.CoreLib/src/System/Reflection/ConstructorInvoker.cs b/src/libraries/System.Private.CoreLib/src/System/Reflection/ConstructorInvoker.cs
index 67fc0d3..7f3c1a2 100644 (file)
--- a/src/libraries/System.Private.CoreLib/src/System/Reflection/ConstructorInvoker.cs
+++ b/src/libraries/System.Private.CoreLib/src/System/Reflection/ConstructorInvoker.cs
@@ -11,6 +11,17 @@ using static System.Reflection.MethodInvokerCommon;
 
 namespace System.Reflection
 {
+    /// <summary>
+    /// Invokes the method reflected by the provided <see cref="ConstructorInfo"/>.
+    /// </summary>
+    /// <remarks>
+    /// Used for better performance than <seealso cref="ConstructorInfo.Invoke"/> when compatibility with that method
+    /// is not necessary and when the caller can cache the ConstructorInvoker instance for additional invoke calls.<br/>
+    /// Unlike <see cref="ConstructorInfo.Invoke"/>, the invoke methods do not look up default values for arguments when
+    /// <see cref="Type.Missing"/> is specified. In addition, the target constructor may be inlined for performance and not
+    /// appear in stack traces.
+    /// </remarks>
+    /// <seealso cref="MethodInvoker"/>
     public sealed partial class ConstructorInvoker
     {
         private InvokeFunc_ObjSpanArgs? _invokeFunc_ObjSpanArgs;
@@ -24,6 +35,17 @@ namespace System.Reflection
         private readonly RuntimeConstructorInfo _method;
         private readonly bool _needsByRefStrategy;
 
+        /// <summary>
+        /// Creates a new instance of ConstructorInvoker.
+        /// </summary>
+        /// <remarks>
+        /// For performance, the resulting instance should be cached for additional calls.
+        /// </remarks>
+        /// <param name="constructor">The constructor that will be invoked.</param>
+        /// <returns>An instance of a ConstructorInvoker.</returns>
+        /// <exception cref="ArgumentException">
+        /// The <paramref name="constructor"/> is not a runtime-based method.
+        /// </exception>
         public static ConstructorInvoker Create(ConstructorInfo constructor)
         {
             ArgumentNullException.ThrowIfNull(constructor, nameof(constructor));
@@ -46,6 +68,21 @@ namespace System.Reflection
             Initialize(argumentTypes, out _strategy, out _invokerArgFlags, out _needsByRefStrategy);
         }
 
+        /// <summary>
+        /// Invokes the constructor.
+        /// </summary>
+        /// <returns>
+        /// An instance of the class associated with the constructor.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        /// The type that declares the method is an open generic type.
+        /// </exception>
+        /// <exception cref="TargetParameterCountException">
+        /// The correct number of arguments were not provided.
+        /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// The calling convention or signature is not supported.
+        /// </exception>
         public object Invoke()
         {
             if (_argCount != 0)
@@ -56,6 +93,14 @@ namespace System.Reflection
             return InvokeImpl(null, null, null, null);
         }
 
+        /// <summary>
+        /// Invokes the constructor using the specified parameters.
+        /// </summary>
+        /// <inheritdoc cref="Invoke()"/>
+        /// <param name="arg1">The first argument for the invoked method.</param>
+        /// <exception cref="ArgumentException">
+        /// The arguments do not match the signature of the invoked constructor.
+        /// </exception>
         public object Invoke(object? arg1)
         {
             if (_argCount != 1)
@@ -66,6 +111,9 @@ namespace System.Reflection
             return InvokeImpl(arg1, null, null, null);
         }
 
+        /// <inheritdoc cref="Invoke(object?)"/>
+        /// <param name="arg1">The first argument for the invoked method.</param>
+        /// <param name="arg2">The second argument for the invoked method.</param>
         public object Invoke(object? arg1, object? arg2)
         {
             if (_argCount != 2)
@@ -76,6 +124,10 @@ namespace System.Reflection
             return InvokeImpl(arg1, arg2, null, null);
         }
 
+        /// <inheritdoc cref="Invoke(object?)"/>
+        /// <param name="arg1">The first argument for the invoked method.</param>
+        /// <param name="arg2">The second argument for the invoked method.</param>
+        /// <param name="arg3">The third argument for the invoked method.</param>
         public object Invoke(object? arg1, object? arg2, object? arg3)
         {
             if (_argCount !=3)
@@ -86,6 +138,11 @@ namespace System.Reflection
             return InvokeImpl(arg1, arg2, arg3, null);
         }
 
+        /// <inheritdoc cref="Invoke(object?)"/>
+        /// <param name="arg1">The first argument for the invoked method.</param>
+        /// <param name="arg2">The second argument for the invoked method.</param>
+        /// <param name="arg3">The third argument for the invoked method.</param>
+        /// <param name="arg4">The fourth argument for the invoked method.</param>
         public object Invoke(object? arg1, object? arg2, object? arg3, object? arg4)
         {
             if (_argCount != 4)
@@ -137,6 +194,11 @@ namespace System.Reflection
             return InvokeDirectByRef(arg1, arg2, arg3, arg4);
         }
 
+        /// <inheritdoc cref="Invoke(object?)"/>
+        /// <param name="arguments">The arguments for the invoked constructor.</param>
+        /// <exception cref="ArgumentException">
+        /// The arguments do not match the signature of the invoked constructor.
+        /// </exception>
         public object Invoke(Span<object?> arguments)
         {
             int argLen = arguments.Length;

diff --git a/src/libraries/System.Private.CoreLib/src/System/Reflection/MethodInvoker.cs b/src/libraries/System.Private.CoreLib/src/System/Reflection/MethodInvoker.cs
index b5496c3..66a35db 100644 (file)
--- a/src/libraries/System.Private.CoreLib/src/System/Reflection/MethodInvoker.cs
+++ b/src/libraries/System.Private.CoreLib/src/System/Reflection/MethodInvoker.cs
@@ -12,6 +12,17 @@ using static System.Reflection.MethodInvokerCommon;
 
 namespace System.Reflection
 {
+    /// <summary>
+    /// Invokes the method reflected by the provided <see cref="MethodBase"/>.
+    /// </summary>
+    /// <remarks>
+    /// Used for better performance than <seealso cref="MethodBase.Invoke"/> when compatibility with that method
+    /// is not necessary and when the caller can cache the MethodInvoker instance for additional invoke calls.<br/>
+    /// Unlike <see cref="MethodBase.Invoke"/>, the invoke methods do not look up default values for arguments when
+    /// <see cref="Type.Missing"/> is specified. In addition, the target method may be inlined for performance and not
+    /// appear in stack traces.
+    /// </remarks>
+    /// <seealso cref="ConstructorInvoker"/>
     public sealed partial class MethodInvoker
     {
         private InvokeFunc_ObjSpanArgs? _invokeFunc_ObjSpanArgs;
@@ -26,6 +37,17 @@ namespace System.Reflection
         private readonly bool _needsByRefStrategy;
         private readonly bool _isStatic;
 
+        /// <summary>
+        /// Creates a new instance of MethodInvoker.
+        /// </summary>
+        /// <remarks>
+        /// For performance, the resulting instance should be cached for additional calls.
+        /// </remarks>
+        /// <param name="method">The method that will be invoked.</param>
+        /// <returns>An instance of a MethodInvoker.</returns>
+        /// <exception cref="ArgumentException">
+        /// The <paramref name="method"/> is not a runtime-based method.
+        /// </exception>
         public static MethodInvoker Create(MethodBase method)
         {
             ArgumentNullException.ThrowIfNull(method, nameof(method));
@@ -60,6 +82,32 @@ namespace System.Reflection
             Initialize(argumentTypes, out _strategy, out _invokerArgFlags, out _needsByRefStrategy);
         }
 
+        /// <summary>
+        /// Invokes the method using the specified parameters.
+        /// </summary>
+        /// <param name="obj">
+        /// The object on which to invoke the method. If the method is static, this argument is ignored.
+        /// </param>
+        /// <returns>
+        /// An object containing the return value of the invoked method,
+        /// or <c>null</c> if the invoked method does not have a return value.
+        /// </returns>
+        /// <exception cref="TargetException">
+        /// The <para>obj</para> parameter is <c>null</c> and the method is not static.
+        ///
+        /// -or-
+        ///
+        /// The method is not declared or inherited by the class of <para>obj</para>.
+        /// </exception>
+        /// <exception cref="InvalidOperationException">
+        /// The type that declares the method is an open generic type.
+        /// </exception>
+        /// <exception cref="TargetParameterCountException">
+        /// The correct number of arguments were not provided.
+        /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// The calling convention or signature is not supported.
+        /// </exception>
         public object? Invoke(object? obj)
         {
             if (_argCount != 0)
@@ -70,6 +118,12 @@ namespace System.Reflection
             return InvokeImpl(obj, null, null, null, null);
         }
 
+        /// <inheritdoc cref="Invoke(object?)"/>
+        /// <param name="obj"> The object on which to invoke the method. If the method is static, this argument is ignored. </param>
+        /// <param name="arg1">The first argument for the invoked method.</param>
+        /// <exception cref="ArgumentException">
+        /// The arguments do not match the signature of the invoked method.
+        /// </exception>
         public object? Invoke(object? obj, object? arg1)
         {
             if (_argCount != 1)
@@ -80,6 +134,10 @@ namespace System.Reflection
             return InvokeImpl(obj, arg1, null, null, null);
         }
 
+        /// <inheritdoc cref="Invoke(object?)"/>
+        /// <param name="obj"> The object on which to invoke the method. If the method is static, this argument is ignored. </param>
+        /// <param name="arg1">The first argument for the invoked method.</param>
+        /// <param name="arg2">The second argument for the invoked method.</param>
         public object? Invoke(object? obj, object? arg1, object? arg2)
         {
             if (_argCount != 2)
@@ -90,6 +148,11 @@ namespace System.Reflection
             return InvokeImpl(obj, arg1, arg2, null, null);
         }
 
+        /// <inheritdoc cref="Invoke(object?)"/>
+        /// <param name="obj"> The object on which to invoke the method. If the method is static, this argument is ignored. </param>
+        /// <param name="arg1">The first argument for the invoked method.</param>
+        /// <param name="arg2">The second argument for the invoked method.</param>
+        /// <param name="arg3">The third argument for the invoked method.</param>
         public object? Invoke(object? obj, object? arg1, object? arg2, object? arg3)
         {
             if (_argCount != 3)
@@ -100,6 +163,12 @@ namespace System.Reflection
             return InvokeImpl(obj, arg1, arg2, arg3, null);
         }
 
+        /// <inheritdoc cref="Invoke(object?)"/>
+        /// <param name="obj"> The object on which to invoke the method. If the method is static, this argument is ignored. </param>
+        /// <param name="arg1">The first argument for the invoked method.</param>
+        /// <param name="arg2">The second argument for the invoked method.</param>
+        /// <param name="arg3">The third argument for the invoked method.</param>
+        /// <param name="arg4">The fourth argument for the invoked method.</param>
         public object? Invoke(object? obj, object? arg1, object? arg2, object? arg3, object? arg4)
         {
             if (_argCount != 4)
@@ -156,6 +225,12 @@ namespace System.Reflection
             return InvokeDirectByRef(obj, arg1, arg2, arg3, arg4);
         }
 
+        /// <inheritdoc cref="Invoke(object?)"/>
+        /// <param name="obj"> The object on which to invoke the method. If the method is static, this argument is ignored. </param>
+        /// <param name="arguments">The arguments for the invoked method.</param>
+        /// <exception cref="ArgumentException">
+        /// The arguments do not match the signature of the invoked method.
+        /// </exception>
         public object? Invoke(object? obj, Span<object?> arguments)
         {
             int argLen = arguments.Length;