Port System.Runtime.Intrinsics new docs

[carlossanlop]

@dotnet/area-system-runtime-intrinsics @directhex @gewarren PTAL

[gewarren]

Should "This intrinsic is only available on 64-bit processes" be in the remarks instead?

[tannergooding]

I think there's a lot of missing newlines or <para> separators in these as well

[carlossanlop]

@tannergooding I don't see the comments in triple slash split by <para>.

[tannergooding]

They're split by newline in the triple slash, which I don't think has been an issue with the other intrinsic docs; unless we manually fixed those all up in the docs?

[carlossanlop]

I think there's a bug in the tool. I was expecting it to split new lines using <para>. I fixed it manually. Can you please take another look?

[learn-build-service-prod]

Learn Build status updates of commit 91fc144:

✅ Validation status: passed

File	Status	Preview URL	Details
xml/System.Runtime.Intrinsics.Arm/AdvSimd.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.Arm/AdvSimd+Arm64.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.Arm/Sve.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.Arm/SveMaskPattern.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.Arm/SvePrefetchType.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/Avx10v1.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/Avx10v1+V512.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/Avx10v1+X64.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/Avx512DQ.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/Avx512F.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/Avx512F+X64.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/Avx512Vbmi.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/Avx512Vbmi+VL.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/AvxVnni.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/FloatRoundingMode.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics.X86/Sse41.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics/Vector128.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics/Vector128`1.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics/Vector256.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics/Vector256`1.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics/Vector512.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics/Vector512`1.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics/Vector64.xml	✅Succeeded	View
xml/System.Runtime.Intrinsics/Vector64`1.xml	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[carlossanlop]

@tannergooding @gewarren bad news: The compiler generated xmls do not preserve the type in generic types. For example:

https://github.com/dotnet/runtime/blob/50d6cad649aad2bfa4069268eddd16fd51ec5cf3/src/libraries/System.Private.CoreLib/src/System/Runtime/Intrinsics/Vector64.cs#L348-L353C44

        /// <summary>Converts a <see cref="Vector64{Single}" /> to a <see cref="Vector64{Int32}" /> using platform specific behavior on overflow.</summary>
        /// <param name="vector">The vector to convert.</param>
        /// <returns>The converted vector.</returns>
        [Intrinsic]
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static unsafe Vector64<int> ConvertToInt32Native(Vector64<float> vector)

When built, shows the following output under D:\runtime\artifacts\bin\coreclr\windows.x64.Release\IL\System.Private.CoreLib.xml:

        <member name="M:System.Runtime.Intrinsics.Vector128.ConvertToInt32Native(System.Runtime.Intrinsics.Vector128{System.Single})">
            <summary>Converts a <see cref="T:System.Runtime.Intrinsics.Vector128`1" /> to a <see cref="T:System.Runtime.Intrinsics.Vector128`1" /> platform specific behavior on overflow.</summary>
            <param name="vector">The vector to convert.</param>
            <returns>The converted vector.</returns>
        </member>

So our options are:

• Live with it.
• Fix them manually here (very labor intensive).
• Find a way to indicate the <see crefs> in triple slash comments that will preserve the typed generic argument. I suspect it might be possible, because as you can see, the DocId preserved the typed generic argument, but the comments did not.

[tannergooding]

Find a way to indicate the in triple slash comments that will preserve the typed generic argument. I suspect it might be possible, because as you can see, the DocId preserved the typed generic argument, but the comments did not.

If there's a preferred way to state it instead of <see cref="Vector64{Single}" /> then it should be possible to do a find/replace here to fix it up on the XML doc comment side.

Perhaps <see cref="Vector64{T}" /> of <see cref="Single" /> or similar would be sufficient?

[tannergooding]

Would appreciate weigh-in from @gewarren on the preferred way for this to be "displayed" or otherwise surfaced for the docs page side of things, and then I can automate the replacement

For returns and similar, we do: Vector128<Int32>

Where the first links to the Vector128<T>

So if there were maybe something like <see cref="Vector64{T}" />&lt;<see cref="Single" />&gt;, but with something to have the first part show as just Vector64 and not as Vector64<T>

[gewarren]

Would appreciate weigh-in from @gewarren on the preferred way for this to be "displayed" or otherwise surfaced for the docs page side of things, and then I can automate the replacement

My preference would just be use code tags or langword instead of see cref. E.g.:

Converts a <see langword="Vector64<Single>" /> to ...

[carlossanlop]

and then I can automate the replacement

Thank you so much, @tannergooding. It's really frustrating that the intellisense xmls do not respect it when they're generated.

[gewarren]

Closing in favor of #10275.