Document ECMA-335 augment III.1.7.7 recognition for UnscopedRefAttribute and RefSafetyRulesAttribute

[Copilot]

Documents that UnscopedRefAttribute and RefSafetyRulesAttribute are specially recognized by the runtime per ECMA-335 augment III.1.7.7 (from dotnet/runtime#130863), and links out to the augment for the full IL restriction rules.

Changes

• UnscopedRefAttribute — Added remarks explaining the augment: applying it to a value type instance method lets this escape; when absent, an optimizing compiler can rely on this not escaping (e.g., to eliminate boxing). Notes the runtime relies on it (can't be stripped) and that its effect only holds in a module also annotated with RefSafetyRulesAttribute.
• RefSafetyRulesAttribute — Replaced the placeholder remarks with a description of the module-level opt-in and version value, links to the augment, and notes the runtime can't strip it.

Both entries follow repo style (contractions, "might"/"can" over "may") and link to the augment's #iii177-opt-in-restrictions anchor. No claim that dynamic IL emitters must apply either attribute, since omitting them is always conservatively correct.

---

Internal previews

File	Preview link
xml/System.Diagnostics.CodeAnalysis/UnscopedRefAttribute.xml	xml/System.Diagnostics.CodeAnalysis/UnscopedRefAttribute.xml
xml/System.Runtime.CompilerServices/RefSafetyRulesAttribute.xml	xml/System.Runtime.CompilerServices/RefSafetyRulesAttribute.xml

[Copilot]

Pull request overview

Updates the ECMA XML reference docs to explain that UnscopedRefAttribute and RefSafetyRulesAttribute are specially recognized by the runtime per ECMA-335 augment III.1.7.7, and links to the spec addendum for the full opt-in IL restriction rules.

Changes:

• Expanded RefSafetyRulesAttribute remarks to describe module-level opt-in semantics and provide a spec addendum link.
• Extended UnscopedRefAttribute remarks with runtime recognition details, an example of this escaping for value-type instance methods, and the dependency on RefSafetyRulesAttribute.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
xml/System.Runtime.CompilerServices/RefSafetyRulesAttribute.xml	Replaces placeholder remarks with ECMA-335 augment explanation and link.
xml/System.Diagnostics.CodeAnalysis/UnscopedRefAttribute.xml	Adds augment-based runtime-recognition remarks and clarifies interaction with RefSafetyRulesAttribute.

Comments suppressed due to low confidence (1)

xml/System.Diagnostics.CodeAnalysis/UnscopedRefAttribute.xml:47

• Grammar/linking: "IL that reference" should be "IL that references" (IL is singular), and the final mention of RefSafetyRulesAttribute is in backticks, so it won't link like the earlier xref.

This attribute is specially recognized by the runtime. ECMA-335 augment III.1.7.7 defines restrictions on valid IL that reference this attribute. For example, when this attribute is applied to an instance method of a value type, the `this` argument is allowed to escape the method. When the attribute is absent, an optimizing compiler can rely on `this` not escaping to further optimize certain code patterns, such as eliminating boxing. For more information, see the [ECMA-335 CLI Specification Addendum](https://github.com/dotnet/runtime/blob/main/docs/design/specs/Ecma-335-Augments.md#iii177-opt-in-restrictions), Sec. III.1.7.7 ("Opt-in restrictions").

Because the runtime relies on this attribute, it can't be stripped from an assembly. The restrictions defined by augment III.1.7.7 apply only when the <xref:System.Runtime.CompilerServices.RefSafetyRulesAttribute> is present on the module, so this attribute has its documented effect only in a module that's also annotated with `RefSafetyRulesAttribute`.