Update ComWrappers.xml

Author: AaronRobinsonMSFT

xml/System.Runtime.InteropServices/ComWrappers.xml

@@ -25,7 +25,59 @@
  </Attributes>
  <Docs>
  <summary>Class for managing wrappers of COM IUnknown types.</summary>
- <remarks>To be added.</remarks>
+ <remarks>
+ <format type="text/markdown"><![CDATA[ 
+ 
+## Remarks
+
+The [`ComWrappers`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.comwrappers) API is used to provide support for the `IUnknown` ABI independent of the built-in COM interoperability support. `ComWrappers` API exposes the minimal runtime support needed for developers to replace the built-in version in an efficient manner.
+
+Traditionally in the runtime a native proxy to managed object is called a COM Callable Wrapper (CCW) and managed proxy to a native object is called a Runtime Callable Wrapper (RCW), but those terms when used here should not be confused with the built-in features of the same name (i.e. [CCW](https://docs.microsoft.com/dotnet/standard/native-interop/com-callable-wrapper) and [RCW](https://docs.microsoft.com/dotnet/standard/native-interop/runtime-callable-wrapper)). Unlike the built-in features a majority of the responsibility for accurate lifetime management, dispatching methods, and marshalling of arguments and return values is left to the `ComWrappers` implementer.
+
+Minimal support is defined by the following features:
+1. Efficient mapping between a managed object and a native proxy (e.g. CCW).
+2. Efficient mapping between a native `IUnknown` and its managed proxy (e.g. RCW).
+3. Integration with the Garbage Collector through the [`IReferenceTrackerHost`](https://docs.microsoft.com/windows/win32/api/windows.ui.xaml.hosting.referencetracker/nn-windows-ui-xaml-hosting-referencetracker-ireferencetrackerhost) interface contract.
+ - Leveraging this is a very advanced scenario.
+
+### Proxy state
+
+Provided below are descriptions and illustrations of proxy state after their respective creation.
+
+In the below illustrations, a strong reference is depicted as a solid line (i.e. `===`) and a weak reference is depicted as a dashed line (i.e. `= = =`). The terms "strong" and "weak" reference should be interpreted as "extending lifetime" and "not extending lifetime" as opposed to implying a specific implementation.
+
+The state of the managed object and native proxy after a call to [`ComWrappers.GetOrCreateComInterfaceForObject`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.comwrappers.getorcreatecominterfaceforobject) is illustrated below.
+
+```
+ -------------------- ----------------------
+| Manage object | | Native proxy |
+| | | Ref count: 1 |
+| ---------------- | | ------------------ |
+| | Weak reference |=| = = = = = = = >| | Strong reference | |
+| | to proxy | |<===============|=| to object | |
+| ---------------- | | ------------------ |
+ -------------------- ----------------------
+```
+
+The state of the native object and managed proxy after a call to [`ComWrappers.GetOrCreateObjectForComInstance`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.comwrappers.getorcreateobjectforcominstance) is illustrated below. The concept of "identity" follows the [rules for `IUnknown`](https://docs.microsoft.com/windows/win32/com/rules-for-implementing-queryinterface#objects-must-have-identity).
+
+```
+ ------------------ ------------------
+| Native object |< = = = = = =| |
+| Ref count: +1 | | Mapping from |
+ ------------------ | native identity |
+ ------------------------ | to managed proxy |
+| Managed proxy |< = = =| |
+| Created by ComWrappers | ------------------
+| implementer. |
+| Optional AddRef() on |
+| native object. |
+ ------------------------
+```
+Observe in the above illustration only weak references exist from the runtime perspective. The `+1` reference count on the native object is assumed to be performed by the managed proxy creator (i.e. `ComWrappers` implementer) to ensure the associated lifetime between the native object and its managed proxy. There is an optional strong reference (i.e. `AddRef()`) mentioned in the managed proxy, which is used to support scenario (3) above - see [`CreateObjectFlags.TrackerObject`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.createobjectflags). With this optional strong reference the reference count would be `+2`.
+
+ ]]></format>
+ </remarks>
  </Docs>
  <Members>
  <Member MemberName=".ctor">