Add documentation links for ByRef fields and byref-like generics

[Copilot]

Description

Adds reference links to improve documentation clarity for ByRef fields and byref-like generics features.

The changes document the C# language support requirements, add concrete motivating examples of implemented features, and clarify the current state of certain constructs.

Changes

• docs/design/specs/Ecma-335-Augments.md:

  • Added inline links to the sunset restricted types proposal and Sunset restricted types roslyn#64811 in the "Ref Fields" section describing the desired support for generalizing ByRef fields and converting TypedReference, ArgIterator, and RuntimeArgumentHandle to follow normal ref struct rules.
  • Added the same links to the "ByRefLike types in generics" section for consistency and completeness.
  • Added a link to the ref struct Generic Parameters C# language counterpart in the "ByRefLike types in generics" section.
  • Link order: sunset restricted types proposal is listed first, followed by the dotnet/roslyn issue in both sections.

• docs/design/features/byreflike-generics.md:

  • Added motivating examples of features that were actually built:
    • Combined Action<Span<char>> and Func<int, Span<byte>> into a single bullet demonstrating delegate-based APIs with Span<T> parameters and return types.
    • Added string.Create<TState>(int length, TState state, SpanAction<char, TState> action) example showing efficient string creation using stack-allocated buffers with ByRefLike types in generic parameters.
  • Clarified that Span<TypedReference> and Span<Span<char>> are potential future additions rather than currently enabled features.
  • Added link to the C# language specification explaining why these constructs were not enabled by this feature.

Original prompt

Create PR that links to dotnet/roslyn#64811 from "In order to support these scenarios, support for generalizing ByRef fields, and converting TypedReference, ArgIterator and RuntimeArgumentHandle into following the normal rules of C# ref structs is desired"

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[GeeLaw]

The link should also be added in "ByRefLike types in generics" (section after "Ref Fields").

[jkotas]

@copilot Please change mention of Span<TypedReference> and Span<Span<char>> in https://github.com/dotnet/runtime/blob/main/docs/design/features/byreflike-generics.md to potential future addition since these constructs were not enabled by this feature. Link to https://github.com/dotnet/csharplang/blob/e8dbda9ab73cbba592206084553a08a6791a272d/proposals/csharp-13.0/ref-struct-interfaces.md#spanspant for additional context.

[Copilot]

@copilot Please change mention of Span<TypedReference> and Span<Span<char>> in https://github.com/dotnet/runtime/blob/main/docs/design/features/byreflike-generics.md to potential future addition s...

Done in commit 11fd35d. Updated the text to clarify these are "potential future additions" and added a link to the C# language specification section explaining why these constructs were not enabled.

[jkotas]

The link should also be added in "ByRefLike types in generics" (section after "Ref Fields").

@copilot Address this feedback

[jkotas]

@GeeLaw @huoyaoyuan Does this look good?

[Copilot]

Pull request overview

This PR enhances documentation for ByRef fields and byref-like generics by adding reference links to C# language proposals and related issues, along with concrete examples of implemented features.

Changes:

• Added documentation links connecting runtime specifications to C# language proposals for ref fields and byref-like generics
• Clarified which features are currently implemented versus potential future additions
• Added concrete motivating examples showing real-world usage of byref-like types in generic parameters

Reviewed changes

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

File	Description
docs/design/specs/Ecma-335-Augments.md	Added links to C# language proposals for ref fields and byref-like generics, and split the ref fields section into two paragraphs for better clarity
docs/design/features/byreflike-generics.md	Added concrete examples of implemented features (Action/Func with Span, string.Create) and clarified that Span and Span<Span> are potential future additions

[huoyaoyuan]

It looks a bit clear now.

[GeeLaw]

Under "ByRefLike types in generics", it's not pointed out that the runtime currently doesn't support substituting TypedReference to allows ref struct --- this is not just a C# restriction.

type as generic argument	C#	runtime
TypedReference	does not compile	exception upon MakeGenericXyz
ArgIterator	does not compile	MakeGenericXyz succeeds
RuntimeArgumentHandle	does not compile	MakeGenericXyz succeeds

Given the status of TypedReference, I'm not sure if the support for the two is accidental or intended in the current release of the runtime.

[jkotas]

I'm not sure if the support for the two is accidental or intended in the current release of the runtime.

It is unfinished feature. I would not recommend depending on it.

[jkotas]

In general, MakeGeneric API is less strict than C#.

[jkotas]

/ba-g markdown change only