Skip to content

Minor improvement to linker descriptor documentation #127015

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mrvoorhe wants to merge 1 commit into
base: main
Choose a base branch
from
+28 −28
Open

Minor improvement to linker descriptor documentation #127015

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 28 additions & 28 deletions docs/tools/illink/data-formats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Descriptor XML can also be passed to the trimmer on the command via the [`-x` pa
```xml
<linker>
<assembly fullname="Assembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null">
<type fullname="Assembly.Foo" preserve="all" />
<type fullname="Namespace.Foo" preserve="all" />
</assembly>
</linker>
```
Expand All @@ -62,25 +62,25 @@ The `required` attribute specifies that if the type is not marked, during the ma
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A" preserve="all" />
<type fullname="Namespace.A" preserve="all" />

<!-- No "preserve" attribute and no members specified means preserve all members -->
<type fullname="Assembly.B" />
<type fullname="Namespace.B" />

Copilot AI Apr 16, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line (and a few others in the XML snippets) has trailing whitespace at end-of-line. In Markdown this can create unintended hard line breaks and also tends to fail whitespace hygiene checks; please trim trailing spaces in the examples.

Copilot uses AI. Check for mistakes.

<!-- Preserve the type declaration only -->
<type fullname="Assembly.C" preserve="nothing" />
<type fullname="Namespace.C" preserve="nothing" />

<!-- Preserve a nested type -->
<type fullname="Assembly.D/Nested" preserve="all" />
<type fullname="Namespace.D/Nested" preserve="all" />

<!-- Preserve all types with the prefix in their name -->
<type fullname="Assembly.Prefix*" />
<type fullname="Namespace.Prefix*" />

<!-- Preserve the type if the type is used. If the type is not used it will be removed -->
<type fullname="Assembly.E" required="false" />
<type fullname="Namespace.E" required="false" />

<!-- Type with generics in the signature -->
<type fullname="Assembly.G`1" />
<type fullname="Namespace.G`1" />
</assembly>
</linker>
```
Expand All @@ -92,10 +92,10 @@ The `required` attribute specifies that if the type is not marked, during the ma
<assembly fullname="Assembly">

<!-- Preserve all fields on a type -->
<type fullname="Assembly.A" preserve="fields" />
<type fullname="Namespace.A" preserve="fields" />

<!-- Preserve all methods on a type -->
<type fullname="Assembly.B" preserve="methods" />
<type fullname="Namespace.B" preserve="methods" />
</assembly>
</linker>
```
Expand All @@ -107,7 +107,7 @@ The `required` attribute specifies that if the type is not marked, during the ma
<assembly fullname="Assembly">

<!-- Preserves all types who's fully qualified type name matches the regular expression -->

Copilot AI Apr 16, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo in the comment: “who's” should be “whose”.

Suggested change
<!-- Preserves all types who's fully qualified type name matches the regular expression -->
<!-- Preserves all types whose fully qualified type name matches the regular expression -->

Copilot uses AI. Check for mistakes.
<type fullname="Assembly.Namespace*" />
<type fullname="Namespace.Namespace*" />

<!-- Preserve all types within the specified namespace -->
<namespace fullname="Assembly.Namespace" />
Comment on lines 109 to 113

Copilot AI Apr 16, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this example, the comment says the type name matches a “regular expression”, but the sample uses the * wildcard pattern (as in the earlier prefix examples). Also, <type fullname="Namespace.Namespace*" /> and <namespace fullname="Assembly.Namespace" /> use different prefixes, which undermines the doc’s goal of showing assembly name and namespace aren’t inherently related. Consider updating the wording to describe wildcard matching and aligning the sample namespace/type values.

Copilot uses AI. Check for mistakes.
Expand All @@ -120,7 +120,7 @@ The `required` attribute specifies that if the type is not marked, during the ma
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<field signature="System.Int32 field1" />

<!-- Field by name rather than signature -->
Expand All @@ -139,7 +139,7 @@ The `required` attribute specifies that if the type is not marked, during the ma
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<method signature="System.Void Method1()" />
<method signature="System.Void Method2(System.Int32,System.String)" />

Expand All @@ -161,7 +161,7 @@ The `required` attribute specifies that if the type is not marked, during the ma
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<!-- Preserve the property, its backing field (if present), getter, and setter methods -->
<property signature="System.Int32 Property1" />

Expand All @@ -188,7 +188,7 @@ The `required` attribute specifies that if the type is not marked, during the ma
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<!-- Preserve the event, it's backing field (if present), add, and remove methods -->
<event signature="System.EventHandler Event1" />

Expand Down Expand Up @@ -232,7 +232,7 @@ The `value` attribute is optional and only required when the method should be ha
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<method signature="System.String TestMethod()" body="stub" value="abcd" />
</type>
</assembly>
Expand All @@ -246,7 +246,7 @@ Entire method body is replaces with `throw` instruction when method is reference
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<method signature="System.String TestMethod()" body="remove" />
</type>
</assembly>
Expand All @@ -273,7 +273,7 @@ are applied, based on feature settings passed via `--feature FeatureName bool`
<linker>
<assembly fullname="Assembly">
<!-- This substitution will apply only if "EnableOptionalFeature" is set to "false" -->
<type fullname="Assembly.A" feature="EnableOptionalFeature" featurevalue="false">
<type fullname="Namespace.A" feature="EnableOptionalFeature" featurevalue="false">
<method signature="System.String TestMethod()" body="stub" />
</type>
</assembly>
Expand All @@ -288,11 +288,11 @@ Note that this will only have an effect where it is applied - the default value
<linker>
<assembly fullname="Assembly">
<!-- This method will be preserved if "EnableDefaultFeature" is "true" or unspecified -->
<type fullname="Assembly.A" feature="EnableDefaultFeature" featurevalue="true" featuredefault="true">
<type fullname="Namespace.A" feature="EnableDefaultFeature" featurevalue="true" featuredefault="true">
<method signature="System.String TestMethod()" />
</type>
<!-- This method will only be preserved if "EnableDefaultFeature" is "true", not if it is unspecified-->
<type fullname="Assembly.A" feature="EnableDefaultFeature" featurevalue="true">
<type fullname="Namespace.A" feature="EnableDefaultFeature" featurevalue="true">
<method signature="System.String TestMethod2()" />
</type>
</assembly>
Expand Down Expand Up @@ -351,7 +351,7 @@ This allows to add a custom attribute to a class, interface, delegate, struct or
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<attribute fullname="CustomAttributeName" assembly="AssemblyName">
<argument>Argument</argument>
</attribute>
Expand All @@ -365,7 +365,7 @@ This allows to add a custom attribute to a class, interface, delegate, struct or
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<field name="MyTypeField">
<attribute fullname="System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute" assembly="System.Runtime">
<argument type="System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes">DefaultConstructor</argument>
Expand All @@ -381,7 +381,7 @@ This allows to add a custom attribute to a class, interface, delegate, struct or
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<property name="MyTypeProperty">
<attribute fullname="System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute" assembly="System.Runtime">
<argument type="System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes">DefaultConstructor</argument>
Expand All @@ -397,7 +397,7 @@ This allows to add a custom attribute to a class, interface, delegate, struct or
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<event name="MyTypeEvent">
<attribute fullname="CustomAttribute" assembly="AssemblyName">
<argument>ArgumentValue</argument>
Expand All @@ -413,7 +413,7 @@ This allows to add a custom attribute to a class, interface, delegate, struct or
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<method signature="System.Void Method1(System.Type)">
<parameter name="typeParameter">
<attribute fullname="System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute" assembly="System.Runtime">
Expand Down Expand Up @@ -445,7 +445,7 @@ This allows to add a custom attribute to a class, interface, delegate, struct or
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<method signature="System.Void Method1(System.Type, System.Type, System.Type)">
<parameter name="typeParameter1">
<attribute fullname="System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute" assembly="System.Runtime">
Expand Down Expand Up @@ -473,7 +473,7 @@ This allows to add a custom attribute to a class, interface, delegate, struct or
```xml
<linker>
<assembly fullname="Assembly">
<type fullname="Assembly.A">
<type fullname="Namespace.A">
<type name="NestedType">
<property name="MyTypeField">
<attribute fullname="System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute" assembly="System.Runtime">
Expand Down Expand Up @@ -510,7 +510,7 @@ attributes are applied.
<linker>
<assembly fullname="Assembly">
<!-- The attribute will apply only if "EnableOptionalFeature" is set to "false" -->
<type fullname="Assembly.A" feature="EnableOptionalFeature" featurevalue="false">
<type fullname="Namespace.A" feature="EnableOptionalFeature" featurevalue="false">
<method signature="System.String TestMethod()">
<return>
<attribute fullname="System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute" assembly="System.Runtime">
Expand Down
Loading