From eabea90040d359e9552e2821d6f7ab3e249a9a4d Mon Sep 17 00:00:00 2001
From: Jeremy Koritzinsky <jekoritz@microsoft.com>
Date: Tue, 11 Jul 2023 11:46:35 -0700
Subject: [PATCH] Add more docs for new COM source generator types (#88627)

---
 .../Marshalling/ComInterfaceMarshaller.cs             | 18 +++++++++++++++++-
 .../Runtime/InteropServices/Marshalling/ComObject.cs  |  9 ++++++---
 .../Marshalling/GeneratedComClassAttribute.cs         |  6 ++++++
 .../Marshalling/GeneratedComInterfaceAttribute.cs     |  3 +++
 .../Marshalling/UniqueComInterfaceMarshaller.cs       | 19 +++++++++++++++++++
 5 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComInterfaceMarshaller.cs b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComInterfaceMarshaller.cs
index ee05af5..6551fe1 100644
--- a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComInterfaceMarshaller.cs
+++ b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComInterfaceMarshaller.cs
@@ -6,7 +6,7 @@ using System.Runtime.Versioning;
 namespace System.Runtime.InteropServices.Marshalling
 {
     /// <summary>
-    /// COM interface marshaller using a StrategyBasedComWrappers instance
+    /// COM interface marshaller using a <see cref="StrategyBasedComWrappers" /> instance
     /// </summary>
     /// <remarks>
     /// This marshaller will always pass the <see cref="CreateObjectFlags.Unwrap"/> flag
@@ -22,6 +22,11 @@ namespace System.Runtime.InteropServices.Marshalling
     {
         private static readonly Guid? TargetInterfaceIID = StrategyBasedComWrappers.DefaultIUnknownInterfaceDetailsStrategy.GetIUnknownDerivedDetails(typeof(T).TypeHandle)?.Iid;
 
+        /// <summary>
+        /// Convert a managed object to a COM interface pointer for the COM interface represented by <typeparamref name="T"/>.
+        /// </summary>
+        /// <param name="managed">The managed object</param>
+        /// <returns>The COM interface pointer</returns>
         public static void* ConvertToUnmanaged(T? managed)
         {
             if (managed == null)
@@ -35,6 +40,13 @@ namespace System.Runtime.InteropServices.Marshalling
             return CastIUnknownToInterfaceType(unknown);
         }
 
+        /// <summary>
+        /// Convert a COM interface pointer to a managed object.
+        /// </summary>
+        /// <param name="unmanaged">The COM interface pointer</param>
+        /// <remarks>
+        /// If the passed in COM interface pointer wraps a managed object, this method returns the underlying object.
+        /// </remarks>
         public static T? ConvertToManaged(void* unmanaged)
         {
             if (unmanaged == null)
@@ -44,6 +56,10 @@ namespace System.Runtime.InteropServices.Marshalling
             return (T)StrategyBasedComWrappers.DefaultMarshallingInstance.GetOrCreateObjectForComInstance((nint)unmanaged, CreateObjectFlags.Unwrap);
         }
 
+        /// <summary>
+        /// Release a reference to the COM interface pointer.
+        /// </summary>
+        /// <param name="unmanaged">A COM interface pointer.</param>
         public static void Free(void* unmanaged)
         {
             if (unmanaged != null)
diff --git a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComObject.cs b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComObject.cs
index 0e2fc37..71fca5a 100644
--- a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComObject.cs
+++ b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/ComObject.cs
@@ -30,6 +30,9 @@ namespace System.Runtime.InteropServices.Marshalling
             _instancePointer = IUnknownStrategy.CreateInstancePointer(thisPointer);
         }
 
+        /// <summary>
+        /// Release all references to the underlying COM object.
+        /// </summary>
         ~ComObject()
         {
             CacheStrategy.Clear(IUnknownStrategy);
@@ -54,11 +57,11 @@ namespace System.Runtime.InteropServices.Marshalling
         internal bool UniqueInstance { get; init; }
 
         /// <summary>
-        /// Releases all references owned by this ComObject if it is a unique instance.
+        /// Releases all references owned by this <see cref="ComObject" /> if it is a unique instance.
         /// </summary>
         /// <remarks>
-        /// This method does nothing if the ComObject was not created with
-        /// CreateObjectFlags.UniqueInstance.
+        /// This method does nothing if the <see cref="ComObject" /> was not created with
+        /// <see cref="CreateObjectFlags.UniqueInstance" />.
         /// </remarks>
         public void FinalRelease()
         {
diff --git a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/GeneratedComClassAttribute.cs b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/GeneratedComClassAttribute.cs
index a3ee297..5403590 100644
--- a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/GeneratedComClassAttribute.cs
+++ b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/GeneratedComClassAttribute.cs
@@ -3,6 +3,12 @@
 
 namespace System.Runtime.InteropServices.Marshalling
 {
+    /// <summary>
+    /// Specifies that code should be generated to enable exposing the attributed class to COM.
+    /// </summary>
+    /// <remarks>
+    /// This attribute is only valid on types that implement at least one <see cref="GeneratedComInterfaceAttribute"/>-attributed interface.
+    /// </remarks>
     [AttributeUsage(AttributeTargets.Class)]
     public sealed class GeneratedComClassAttribute : Attribute
     {
diff --git a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/GeneratedComInterfaceAttribute.cs b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/GeneratedComInterfaceAttribute.cs
index 8c9ffc7..60bc272 100644
--- a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/GeneratedComInterfaceAttribute.cs
+++ b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/GeneratedComInterfaceAttribute.cs
@@ -3,6 +3,9 @@
 
 namespace System.Runtime.InteropServices.Marshalling
 {
+    /// <summary>
+    /// Specifies that the attributed type is a COM interface and that the source generator should generate code for it.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Interface)]
     public class GeneratedComInterfaceAttribute : Attribute
     {
diff --git a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/UniqueComInterfaceMarshaller.cs b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/UniqueComInterfaceMarshaller.cs
index 2e48b89..c1e1e1c 100644
--- a/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/UniqueComInterfaceMarshaller.cs
+++ b/src/libraries/System.Runtime.InteropServices/src/System/Runtime/InteropServices/Marshalling/UniqueComInterfaceMarshaller.cs
@@ -21,6 +21,11 @@ namespace System.Runtime.InteropServices.Marshalling
     [CustomMarshaller(typeof(CustomMarshallerAttribute.GenericPlaceholder), MarshalMode.Default, typeof(UniqueComInterfaceMarshaller<>))]
     public static unsafe class UniqueComInterfaceMarshaller<T>
     {
+        /// <summary>
+        /// Convert a managed object to a COM interface pointer for the COM interface represented by <typeparamref name="T"/>.
+        /// </summary>
+        /// <param name="managed">The managed object</param>
+        /// <returns>The COM interface pointer</returns>
         public static void* ConvertToUnmanaged(T? managed)
         {
             if (managed == null)
@@ -34,6 +39,15 @@ namespace System.Runtime.InteropServices.Marshalling
             return ComInterfaceMarshaller<T>.CastIUnknownToInterfaceType(unknown);
         }
 
+
+        /// <summary>
+        /// Convert a COM interface pointer to a managed object.
+        /// </summary>
+        /// <param name="unmanaged">The COM interface pointer</param>
+        /// <returns>A managed object that represents the passed in COM interface pointer.</returns>
+        /// <remarks>
+        /// If the passed in COM interface pointer wraps a managed object, this method returns the underlying object.
+        /// </remarks>
         public static T? ConvertToManaged(void* unmanaged)
         {
             if (unmanaged == null)
@@ -43,6 +57,11 @@ namespace System.Runtime.InteropServices.Marshalling
             return (T)StrategyBasedComWrappers.DefaultMarshallingInstance.GetOrCreateObjectForComInstance((nint)unmanaged, CreateObjectFlags.Unwrap | CreateObjectFlags.UniqueInstance);
         }
 
+
+        /// <summary>
+        /// Release a reference to the COM interface pointer.
+        /// </summary>
+        /// <param name="unmanaged">A COM interface pointer.</param>
         public static void Free(void* unmanaged)
         {
             if (unmanaged != null)
-- 
2.7.4