Minor improvement to linker descriptor documentation#127015
Conversation
The `Assembly.` part in lines such as
```
<type fullname="Assembly.B" />
```
Could be confusing. While it is convention to have the assembly name and namespace match, it's not a requirement.
|
@sbomer Please take a look |
|
Tagging subscribers to this area: @agocke, @dotnet/illink |
There was a problem hiding this comment.
Pull request overview
Updates the ILLink linker descriptor documentation examples to avoid implying that a type’s namespace must match the assembly name, reducing confusion for users writing descriptor XML.
Changes:
- Replaced
Assembly.*type fullname examples withNamespace.*to better reflect that type names are namespace-qualified, not assembly-qualified. - Adjusted multiple XML snippets throughout the doc to consistently use the new placeholder namespace.
| <!-- Preserves all types who's fully qualified type name matches the regular expression --> | ||
| <type fullname="Assembly.Namespace*" /> | ||
| <type fullname="Namespace.Namespace*" /> | ||
|
|
||
| <!-- Preserve all types within the specified namespace --> | ||
| <namespace fullname="Assembly.Namespace" /> |
There was a problem hiding this comment.
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.
| @@ -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 --> | |||
There was a problem hiding this comment.
Typo in the comment: “who's” should be “whose”.
| <!-- 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 --> |
|
|
||
| <!-- No "preserve" attribute and no members specified means preserve all members --> | ||
| <type fullname="Assembly.B" /> | ||
| <type fullname="Namespace.B" /> |
There was a problem hiding this comment.
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.
|
@sbomer Can you merge this? |
The
Assembly.part in lines such asCould be confusing. While it is convention to have the assembly name and namespace match, it's not a requirement.