From c86b6f92645b854edd99c7449441811b4f25d4c9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 5 Dec 2025 18:35:28 +0000
Subject: [PATCH 1/4] Initial plan


From 645bff5496f02bcf9e4ea1220baf11da4196af86 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 5 Dec 2025 18:40:19 +0000
Subject: [PATCH 2/4] Add detailed remarks to TypeMapAttribute and
 TypeMapAssociationAttribute documentation

Co-authored-by: AaronRobinsonMSFT <30635565+AaronRobinsonMSFT@users.noreply.github.com>
---
 .../TypeMapAssociationAttribute`1.xml         | 35 ++++++++++++++++++-
 .../TypeMapAttribute`1.xml                    | 34 +++++++++++++++++-
 2 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/xml/System.Runtime.InteropServices/TypeMapAssociationAttribute`1.xml b/xml/System.Runtime.InteropServices/TypeMapAssociationAttribute`1.xml
index ab425c157f5..d9e429ac1b8 100644
--- a/xml/System.Runtime.InteropServices/TypeMapAssociationAttribute`1.xml
+++ b/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 `TypeMapAssociationAttribute` 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 one of the flags 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 one of the flags that preserves constructors for the storage location.
+- 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 `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's not guaranteed that the `TypeMapAttribute`, `TypeMapAssociationAttribute`, and `TypeMapAssemblyTargetAttribute` attributes are present in the final image after a trimming tool has been run.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
diff --git a/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml b/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml
index 397826d8b65..42685885918 100644
--- a/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml
+++ b/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 `TypeMapAttribute` 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's not guaranteed that the `TypeMapAttribute`, `TypeMapAssociationAttribute`, and `TypeMapAssemblyTargetAttribute` attributes are present in the final image after a trimming tool has been run.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

From 2f5616e2fe4c02fe58d5777945592b16851ef357 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 5 Dec 2025 18:41:53 +0000
Subject: [PATCH 3/4] Fix typo: 'kthe' -> 'the' in TypeMapAttribute parameter
 description

Co-authored-by: AaronRobinsonMSFT <30635565+AaronRobinsonMSFT@users.noreply.github.com>
---
 xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml b/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml
index 42685885918..b9e6caeff1b 100644
--- a/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml
+++ b/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml
@@ -88,7 +88,7 @@ Many of these instructions can be passed a generic parameter. In that case, the
         <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>

From 0fe5e3d469d55ec306d9701ad367f86e90e82a6a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 5 Dec 2025 18:43:26 +0000
Subject: [PATCH 4/4] Improve readability of documentation per code review
 feedback

Co-authored-by: AaronRobinsonMSFT <30635565+AaronRobinsonMSFT@users.noreply.github.com>
---
 .../TypeMapAssociationAttribute`1.xml                         | 4 ++--
 xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml     | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/xml/System.Runtime.InteropServices/TypeMapAssociationAttribute`1.xml b/xml/System.Runtime.InteropServices/TypeMapAssociationAttribute`1.xml
index d9e429ac1b8..4ba79ed2ebf 100644
--- a/xml/System.Runtime.InteropServices/TypeMapAssociationAttribute`1.xml
+++ b/xml/System.Runtime.InteropServices/TypeMapAssociationAttribute`1.xml
@@ -41,8 +41,8 @@ Types used in a managed-to-unmanaged interop operation can use `TypeMapAssociati
 
 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 one of the flags 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 one of the flags that preserves constructors for the storage location.
+- 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.
diff --git a/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml b/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml
index b9e6caeff1b..6bbcf9a3372 100644
--- a/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml
+++ b/xml/System.Runtime.InteropServices/TypeMapAttribute`1.xml
@@ -55,7 +55,7 @@ When an application is trimmed, an entry in the External Type Map is included wh
 - 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 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.