Add remarks showing new method names in .NET 10 #11599
Conversation
|
Tagging subscribers to this area: @dotnet/area-system-runtime-intrinsics |
| @@ -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.UInt8},System.Void*,System.Runtime.Intrinsics.Arm.SvePrefetchType)" /> .NET 10.</remarks> | |||
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Thanks! I pinged on the thread.
Fixes #11427.