From ceb016f768c3077b5dabb395d2db5ec09941b81f Mon Sep 17 00:00:00 2001
From: Jeremy Koritzinsky <jekoritz@microsoft.com>
Date: Fri, 9 Aug 2024 11:39:57 -0700
Subject: [PATCH 1/2] Add new API docs

---
 .../Marshalling/ReadOnlySpanMarshaller.cs       |  3 +++
 .../Runtime/InteropServices/Swift/SwiftTypes.cs |  1 +
 .../Marshalling/ComVariantMarshaller.cs         | 17 +++++++++++++++++
 3 files changed, 21 insertions(+)

diff --git a/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/ReadOnlySpanMarshaller.cs b/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/ReadOnlySpanMarshaller.cs
index 93e6db64729e81..972a1e706a9626 100644
--- a/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/ReadOnlySpanMarshaller.cs
+++ b/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/ReadOnlySpanMarshaller.cs
@@ -188,6 +188,7 @@ public void FromUnmanaged(TUnmanagedElement* unmanaged)
             /// <summary>
             /// Returns the managed value representing the native array.
             /// </summary>
+            /// <returns>A span over managed values of the array.</returns>
             public ReadOnlySpan<T> ToManaged()
             {
                 return new ReadOnlySpan<T>(_managedValues!);
@@ -196,6 +197,7 @@ public ReadOnlySpan<T> ToManaged()
             /// <summary>
             /// Returns a span that points to the memory where the unmanaged elements of the array are stored.
             /// </summary>
+            /// <param name="numElements">The number of elements in the array.</param>
             /// <returns>A span over unmanaged values of the array.</returns>
             public ReadOnlySpan<TUnmanagedElement> GetUnmanagedValuesSource(int numElements)
             {
@@ -205,6 +207,7 @@ public ReadOnlySpan<TUnmanagedElement> GetUnmanagedValuesSource(int numElements)
             /// <summary>
             /// Returns a span that points to the memory where the managed elements of the array should be stored.
             /// </summary>
+            /// <param name="numElements">The number of elements in the array.</param>
             /// <returns>A span where managed values of the array should be stored.</returns>
             public Span<T> GetManagedValuesDestination(int numElements)
             {
diff --git a/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Swift/SwiftTypes.cs b/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Swift/SwiftTypes.cs
index a8c4a18c30d727..58fff0aa269ccb 100644
--- a/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Swift/SwiftTypes.cs
+++ b/src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/Swift/SwiftTypes.cs
@@ -42,6 +42,7 @@ public SwiftSelf(void* value)
     /// Represents the Swift 'self' context when the argument is Swift frozen struct T, which is either enregistered into multiple registers,
     /// or passed by reference in the 'self' register.
     /// </summary>
+    /// <typeparam name="T">The type of the frozen struct to pass in the 'self' context.</typeparam>
     /// <remarks>
     /// <para>
     /// This struct is used to pass the Swift frozen struct T to Swift functions in the context of interop with .NET.
diff --git a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComVariantMarshaller.cs b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComVariantMarshaller.cs
index 9c2375d3a97fa6..d1f945611b4513 100644
--- a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComVariantMarshaller.cs
+++ b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComVariantMarshaller.cs
@@ -22,6 +22,13 @@ public static partial class ComVariantMarshaller
         // VARIANT_BOOL constants.
         private const short VARIANT_TRUE = -1;
         private const short VARIANT_FALSE = 0;
+
+        /// <summary>
+        /// Convert a managed object to an unmanaged <see cref="ComVariant"/>.
+        /// </summary>
+        /// <param name="managed">The managed object</param>
+        /// <returns>A <see cref="ComVariant" /> that represents the provided managed object.</returns>
+        /// <exception cref="ArgumentException">The type of <paramref name="managed"/> is not supported.</exception>
         public static ComVariant ConvertToUnmanaged(object? managed)
         {
             if (managed is null)
@@ -103,6 +110,12 @@ private static unsafe bool TryCreateOleVariantForInterfaceWrapper(object managed
         }
 #pragma warning restore CA1416 // Validate platform compatibility
 
+        /// <summary>
+        /// Convert an unmanaged <see cref="ComVariant"/> to a managed object.
+        /// </summary>
+        /// <param name="unmanaged">The unmanaged variant</param>
+        /// <returns>A managed object that represents the same value as <paramref name="unmanaged"/>.</returns>
+        /// <exception cref="ArgumentException">The type of data stored in <paramref name="unmanaged"/> is not supported.</exception>
         public static unsafe object? ConvertToManaged(ComVariant unmanaged)
         {
 #pragma warning disable CS0618 // Type or member is obsolete
@@ -195,6 +208,10 @@ private static unsafe bool TryCreateOleVariantForInterfaceWrapper(object managed
 #pragma warning restore CS0618 // Type or member is obsolete
         }
 
+        /// <summary>
+        /// Dispose the unmanaged <see cref="ComVariant"/>.
+        /// </summary>
+        /// <param name="unmanaged">The object to dispose.</param>
         public static void Free(ComVariant unmanaged) => unmanaged.Dispose();
 
         /// <summary>

From 7854ef4b2d1b6f3d879ded88b502b29114e2d4b7 Mon Sep 17 00:00:00 2001
From: Jeremy Koritzinsky <jkoritzinsky@gmail.com>
Date: Fri, 9 Aug 2024 13:26:19 -0700
Subject: [PATCH 2/2] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Carlos Sánchez López <1175054+carlossanlop@users.noreply.github.com>
---
 .../Marshalling/ComVariantMarshaller.cs                | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComVariantMarshaller.cs b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComVariantMarshaller.cs
index d1f945611b4513..a824eb5dcce0b1 100644
--- a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComVariantMarshaller.cs
+++ b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComVariantMarshaller.cs
@@ -24,9 +24,9 @@ public static partial class ComVariantMarshaller
         private const short VARIANT_FALSE = 0;
 
         /// <summary>
-        /// Convert a managed object to an unmanaged <see cref="ComVariant"/>.
+        /// Converts a managed object to an unmanaged <see cref="ComVariant"/>.
         /// </summary>
-        /// <param name="managed">The managed object</param>
+        /// <param name="managed">The managed object.</param>
         /// <returns>A <see cref="ComVariant" /> that represents the provided managed object.</returns>
         /// <exception cref="ArgumentException">The type of <paramref name="managed"/> is not supported.</exception>
         public static ComVariant ConvertToUnmanaged(object? managed)
@@ -111,9 +111,9 @@ private static unsafe bool TryCreateOleVariantForInterfaceWrapper(object managed
 #pragma warning restore CA1416 // Validate platform compatibility
 
         /// <summary>
-        /// Convert an unmanaged <see cref="ComVariant"/> to a managed object.
+        /// Converts an unmanaged <see cref="ComVariant"/> to a managed object.
         /// </summary>
-        /// <param name="unmanaged">The unmanaged variant</param>
+        /// <param name="unmanaged">The unmanaged variant.</param>
         /// <returns>A managed object that represents the same value as <paramref name="unmanaged"/>.</returns>
         /// <exception cref="ArgumentException">The type of data stored in <paramref name="unmanaged"/> is not supported.</exception>
         public static unsafe object? ConvertToManaged(ComVariant unmanaged)
@@ -209,7 +209,7 @@ private static unsafe bool TryCreateOleVariantForInterfaceWrapper(object managed
         }
 
         /// <summary>
-        /// Dispose the unmanaged <see cref="ComVariant"/>.
+        /// Disposes the unmanaged <see cref="ComVariant"/>.
         /// </summary>
         /// <param name="unmanaged">The object to dispose.</param>
         public static void Free(ComVariant unmanaged) => unmanaged.Dispose();