Add design usage notes to TypeMapAttribute and TypeMapAssociationAttribute documentation

xml/System.Runtime.InteropServices/TypeMapAssociationAttribute`1.xml

@@ -32,7 +32,40 @@
   <Docs>
     <typeparam name="TTypeMapGroup">The type of the type map group.</typeparam>
     <summary>Represents an attribute that creates a type association between a type and its proxy.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Types used in a managed-to-unmanaged interop operation can use <xref:System.Runtime.InteropServices.TypeMapAssociationAttribute%60%601> to define a conditional link between the source and proxy type. If the source is kept, so is the proxy type. If trimming observes an explicit allocation of the source type, the entry is inserted into the map.
+
+When an application is trimmed, an entry in the Proxy Type Map is included when the "source type" is referenced in one of the following ways in reachable code:
+
+- The argument to the `ldtoken` IL instruction when <xref:System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute> is specified with a flag that preserves constructors for the storage location.
+- Calls to <xref:System.Type.GetType%2A?displayProperty=nameWithType> with a constant string representing the type name when <xref:System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute> is specified with a flag that preserves constructors.
+- The type of a method argument to the `newobj` instruction.
+- The generic argument to the <xref:System.Activator.CreateInstance%60%601> method.
+- The argument to the `box` instruction.
+- The argument to the `newarr` instruction.
+- The argument to the `mkrefany` instruction.
+- The argument to the `refanyval` instruction.
+
+If the type is an interface type and the user could possibly see a <xref:System.RuntimeTypeHandle> for the type as part of a casting or virtual method resolution operation (such as with <xref:System.Runtime.InteropServices.IDynamicInterfaceCastable>), then the following cases also apply:
+
+- The argument to the `isinst` IL instruction.
+- The argument to the `castclass` IL instruction.
+- The owning type of the method argument to `callvirt` or `ldvirtftn`.
+
+Finally, if the trimming tool determines that it's impossible to retrieve a <xref:System.Type> instance that represents the "source type" at runtime, then the entry might be omitted from the Proxy Type Map as its existence is unobservable.
+
+> [!IMPORTANT]
+> Conflicting key/value mappings are not allowed.
+
+> [!NOTE]
+> The underlying format of the produced maps is implementation-defined. Different .NET form factors might use different formats. Additionally, it isn't guaranteed that the <xref:System.Runtime.InteropServices.TypeMapAttribute%60%601>, <xref:System.Runtime.InteropServices.TypeMapAssociationAttribute%60%601>, and <xref:System.Runtime.InteropServices.TypeMapAssemblyTarget%60%601> attributes are present in the final image after a trimming tool has been run.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml

@@ -36,7 +36,39 @@
   <Docs>
     <typeparam name="TTypeMapGroup">The type of the type map group.</typeparam>
     <summary>Represents an attribute that defines type mapping between a string and a type.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Types involved in unmanaged-to-managed interop operations can be referenced in a <xref:System.Runtime.InteropServices.TypeMapAttribute%60%601> assembly attribute that declares the external type system name, a target type, and optionally a "trim target" to determine if the target type should be included in the map. If the constructor that doesn't take a trim target is used, the entry is always emitted into the type map.
+
+When an application is trimmed, an entry in the External Type Map is included when the "trim target" type is referenced in one of the following ways in reachable code:
+
+- The argument to the `ldtoken` IL instruction.
+- The argument to the `unbox` IL instruction.
+- The argument to the `unbox.any` IL instruction.
+- The argument to the `isinst` IL instruction.
+- The argument to the `castclass` IL instruction.
+- The argument to the `box` instruction. (If the trimming tool can determine that this box doesn't escape and could be stack allocated, it can ignore this `box` instruction and any corresponding `unbox` or `unbox.any` instructions.)
+- The argument to the `mkrefany` instruction.
+- The argument to the `refanyval` instruction.
+- The argument to the `newarr` instruction.
+- The type of a method argument to the `newobj` instruction if it's a class type.
+- The owning type of an instance method argument to `call` or `ldftn`, or the owning type of any method argument to `callvirt` or `ldvirtftn`. If the owning type is an interface and the trimming tool can determine that there's only one implementation of the interface, it's free to interpret the method token argument as though it's the method on the only implementing type.
+- The generic argument to the <xref:System.Activator.CreateInstance%60%601> method.
+- Calls to <xref:System.Type.GetType%2A?displayProperty=nameWithType> with a constant string representing the type name.
+
+Many of these instructions can be passed a generic parameter. In that case, the trimming tool should consider type arguments of instantiations of that type as having met one of these rules and include any entries with those types as "trim target" types.
+
+> [!IMPORTANT]
+> Conflicting key/value mappings are not allowed.
+
+> [!NOTE]
+> The underlying format of the produced maps is implementation-defined. Different .NET form factors might use different formats. Additionally, it isn't guaranteed that the <xref:System.Runtime.InteropServices.TypeMapAttribute%60%601>, <xref:System.Runtime.InteropServices.TypeMapAssociationAttribute%60%601>, and <xref:System.Runtime.InteropServices.TypeMapAssemblyTarget%60%601> attributes are present in the final image after a trimming tool has been run.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -56,7 +88,7 @@
         <Parameter Name="target" Type="System.Type" />
       </Parameters>
       <Docs>
-        <param name="value">The string representation of kthe key.</param>
+        <param name="value">The string representation of the key.</param>
         <param name="target">The type value.</param>
         <summary>Initializes a new instance of <see cref="T:System.Runtime.InteropServices.TypeMapAttribute`1" />.</summary>
         <remarks>This mapping is unconditionally inserted into the type map.</remarks>