Skip to content

Add remarks showing new method names in .NET 10 #11599

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

Closed
wants to merge 3 commits into from
Closed

Add remarks showing new method names in .NET 10 #11599

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
da135ad
add remarks showing new method names in .net 10
gewarren Jul 22, 2025
86eda82
fix links
gewarren Jul 22, 2025
f6430d2
fix xref
gewarren Jul 23, 2025
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
8 changes: 4 additions & 4 deletions xml/System.Runtime.Intrinsics.Arm/Sve.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34115,7 +34115,7 @@
<para>void svprfb(svbool_t pg, const void *base, enum svprfop op)</para>
<para> PRFB op, Pg, [Xbase, #0, MUL VL]</para>
</summary>
<remarks>To be added.</remarks>
<remarks>This method was renamed to in <see cref="M:System.Runtime.Intrinsics.Arm.Sve.Prefetch8Bit(System.Numerics.Vector{System.Byte},System.Void*,System.Runtime.Intrinsics.Arm.SvePrefetchType)" /> .NET 10.</remarks>
Copy link
Member

Choose a reason for hiding this comment

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

Do we need these remarks? These were experimental APIs where the previous names were incorrect and so we're just fixing them to be the correct name

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@ericstj and I chatted about it here. The remarks probably aren't "needed", but they don't hurt either and might be helpful to somebody.

Copy link
Member

Choose a reason for hiding this comment

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

I think they might hurt longer term, especially as they persist after making the APIs stable.

The general consideration is that intrinsics have an existing mapping to methods defined in other languages, such as this one mapping to the svprfb C intrinsic and the PRFB Arm64 assembly instruction. So developers may confuse this to be an alias or to have been breaking change to the stable API when really, it's a quirk of the early experimental design that is more a historical artifact you can find by browsing the source commits.

If we were to expose this, I think it'd be better as some separate doc and not part of the main remarks people will see. But we've also intentionally chosen to not surface breaking change docs for typical scenarios involving experimental APIs, only cases where there may be widespread usage or dependency and users are likely to be tripped up. -- And I don't think the platform specific SVE intrinsics for Arm64 qualify for that, they are a niche power user API.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Okay I will close this PR.

especially as they persist after making the APIs stable.

Unless we manually intervene, the old methods will still show up in the .NET 9 version of the API ref.

Copy link
Member

Choose a reason for hiding this comment

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

Unless we manually intervene, the old methods will still show up in the .NET 9 version of the API ref.

But that will still have the EXPERIMENTAL note at the top of the page and will not show up under the .NET 10 version, correct?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It won't show as "experimental" on Learn because they removed the work item to add a banner in June (I'm not sure why). If you want to weigh in on that auto-closure, I think that would help our case to get it implemented. But yes, the old methods won't show up under .NET 10.

Copy link
Member

Choose a reason for hiding this comment

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

Thanks! I pinged on the thread.

</Docs>
</Member>
<Member MemberName="PrefetchInt16">
Expand Down Expand Up @@ -34152,7 +34152,7 @@
<para>void svprfh(svbool_t pg, const void *base, enum svprfop op)</para>
<para> PRFH op, Pg, [Xbase, #0, MUL VL]</para>
</summary>
<remarks>To be added.</remarks>
<remarks>This method was renamed to in <see cref="M:System.Runtime.Intrinsics.Arm.Sve.Prefetch16Bit(System.Numerics.Vector{System.UInt16},System.Void*,System.Runtime.Intrinsics.Arm.SvePrefetchType)" /> .NET 10.</remarks>
</Docs>
</Member>
<Member MemberName="PrefetchInt32">
Expand Down Expand Up @@ -34189,7 +34189,7 @@
<para>void svprfw(svbool_t pg, const void *base, enum svprfop op)</para>
<para> PRFW op, Pg, [Xbase, #0, MUL VL]</para>
</summary>
<remarks>To be added.</remarks>
<remarks>This method was renamed to in <see cref="M:System.Runtime.Intrinsics.Arm.Sve.Prefetch32Bit(System.Numerics.Vector{System.UInt32},System.Void*,System.Runtime.Intrinsics.Arm.SvePrefetchType)" /> .NET 10.</remarks>
</Docs>
</Member>
<Member MemberName="PrefetchInt64">
Expand Down Expand Up @@ -34226,7 +34226,7 @@
<para>void svprfd(svbool_t pg, const void *base, enum svprfop op)</para>
<para> PRFD op, Pg, [Xbase, #0, MUL VL]</para>
</summary>
<remarks>To be added.</remarks>
<remarks>This method was renamed to in <see cref="M:System.Runtime.Intrinsics.Arm.Sve.Prefetch64Bit(System.Numerics.Vector{System.UInt64},System.Void*,System.Runtime.Intrinsics.Arm.SvePrefetchType)" /> .NET 10.</remarks>
</Docs>
</Member>
<Member MemberName="ReciprocalEstimate">
Expand Down