Net10 docs update

[ericstj]

Porting .NET 10.0 intellisense

I had to workaround a few issues I filed.

I also noticed a net change to the repo without any new docs input (simply changes the tool did on its own) - which has also been divided as it's own commit 02f539e

Please look through each and check off when done.

• Changes by only running PortToDocs w/o new API 02f539e
• System.CodeDom docs a4dc410
• System.Collections docs 741d9bd
• System.Diagnostics.CodeAnalysis docs a57899f
• System.Globalization docs 9bfe178
• System.IO docs 80f684d
• System.Net.Http docs dc8c6bd
• System.Numerics.Tensors docs cc987b7
• System.Numerics docs d529454
• System.Reflection docs 8a08e01
• System.Runtime.CompilerServices docs d5087db
• System.Runtime.ExceptionServices docs 77ef11e
• System.Runtime.InteropServices docs 8615484
• System.Runtime.Intrinsics docs 1a9245c
• System.Security.Cryptography docs 6e5da84
• System.Text.Json docs fd355a1
• System.Text docs a62d1a5
• System.Threading docs b159c2a
• System docs dbc53e4

[mconnew]

WCF api's look good

[ericstj]

We're down to just 3 warnings in the build:

xml/System.Numerics.Tensors/Tensor`1.xml	Warning	View	dotnetcontent	dotnet-api	system.numerics	Line 0: [Warning] Cross reference not found: 'System.Numerics.Tensors.TensorSpan1.op_Implicit(System.Numerics.Tensors.TensorSpan{0}@)~System.Numerics.Tensors.ReadOnlyTensorSpan{0}'.Line 0: [Warning] Cross reference not found: 'System.Numerics.Tensors.TensorSpan1.op_Implicit(System.Numerics.Tensors.TensorSpan{0}@)~System.Numerics.Tensors.ReadOnlyTensorSpan{0}'.
xml/System.ServiceModel.Federation/WSTrustChannel.xml	Warning	View	dotnetcontent	dotnet-api	system.servicemodel	Line 0: [Warning] Cross reference not found: 'Microsoft.IdentityModel.Protocols.WsTrust.WsTrustRequest'.Line 0: [Warning] Cross reference not found: 'Microsoft.IdentityModel.Protocols.WsTrust.WsTrustRequest'.Line 0: [Warning] Cross reference not found: 'Microsoft.IdentityModel.Protocols.WsTrust.WsTrustRequest'.
xml/System.ServiceModel.Federation/WSTrustChannelSecurityTokenProvider.xml	Warning	View	dotnetcontent	dotnet-api	system.servicemodel	Line 0: [Warning] Cross reference not found: 'Microsoft.IdentityModel.Protocols.WsTrust.WsTrustRequest'.

Tensor instances were added

Cross reference not found: 'System.Numerics.Tensors.TensorSpan`1.op_Implicit(System.Numerics.Tensors.TensorSpan{`0}@)~System.Numerics.Tensors.ReadOnlyTensorSpan{`0}'.

I suspect we need to fix up that cross-reference. I'll see if I can determine what it should be.

The Microsoft.IdentityModel.Protocols.WsTrust.WsTrustRequest references are pre-existing and those warnings were part of past builds. They are showing up here because the tool touched the files.

[gewarren]

Cross reference not found: 'System.Numerics.Tensors.TensorSpan1.op_Implicit(System.Numerics.Tensors.TensorSpan{0}@)~System.Numerics.Tensors.ReadOnlyTensorSpan{`0}'.

I suspect we need to fix up that cross-reference. I'll see if I can determine what it should be.

This looks like it might be a bug, because the DocId in the inheritdoc seems to match the DocId in the method exactly.

[ericstj]

Yeah I found the same. I'm not sure why the build is claiming it doesn't match. Can we see if there's some consequence of this warning in the generated docs?
https://github.com/dotnet/dotnet-api-docs/pull/11847/files#diff-6701d2dcae9f3bf9e3ad003603dff1a26d7259d5d4d47ddf7646e9676e3c1000R1139

I could just remove that reference in order to avoid the warning. Just for my information -- what value does inheritdoc have when persisted in these files? I'm seeing the content is already duplicated in source, is inheritdoc left as a breadcrumb, or does it have an observable output in the final docs / build process?

[gewarren]

Reviewed through WeakGCHandle.

[gewarren]

Can we see if there's some consequence of this warning in the generated docs?

Preview:

I've added this case to an existing internal work item for inheritdoc doc IDs.

I could just remove that reference in order to avoid the warning. Just for my information -- what value does inheritdoc have when persisted in these files?

I don't see inheritdoc in the HTML, but it remains in the XML in dotnet-api-docs.

[gewarren]

GitHub has pretty much ground to a halt when I make suggestions now (it does that as the number of suggestions grows) so I'll commit my remaining review suggestions directly.

[ericstj]

The fixup of incorrectly escaped <para and <see actually caught a few problems in existing docs 👍

I think I was able to apply all feedback. I had to use VS code and apply somewhat manually in a few cases due to line number changes.

[gewarren]

The fixup of incorrectly escaped <para and <see actually caught a few problems in existing docs

This is probably a bug in api-docs-sync that should be fixed.

[ericstj]

The fixup of incorrectly escaped <para and <see actually caught a few problems in existing docs

This is probably a bug in api-docs-sync that should be fixed.

I found the problem. It's actually misinterpreting other syntax as a markdown link due to use of [](): https://github.com/dotnet/runtime/blob/925205d06d82ce5e0d24e4e313fd66887fe89795/src/libraries/System.Private.CoreLib/src/System/Runtime/Intrinsics/Arm/Sve.cs#L92

///   <para>svbool_t svacgt[_f64](svbool_t pg, svfloat64_t op1, svfloat64_t op2)</para> 

I'll undo the change I made and try to get it to render this correctly.

[ericstj]

I opened dotnet/api-docs-sync#180 to track the other mangling of para tags that we saw in this.

[ericstj]

The fixup of incorrectly escaped <para and <see actually caught a few problems in existing docs

This is probably a bug in api-docs-sync that should be fixed.

I found the problem. It's actually misinterpreting other syntax as a markdown link due to use of : https://github.com/dotnet/runtime/blob/925205d06d82ce5e0d24e4e313fd66887fe89795/src/libraries/System.Private.CoreLib/src/System/Runtime/Intrinsics/Arm/Sve.cs#L92

///   <para>svbool_t svacgt[_f64](svbool_t pg, svfloat64_t op1, svfloat64_t op2)</para> 

I'll undo the change I made and try to get it to render this correctly.

https://review.learn.microsoft.com/en-us/dotnet/api/system.runtime.intrinsics.arm.sve.compareequal?view=net-9.0&viewFallbackFrom=net-10.0-pp&branch=pr-en-us-11847

This is looking better.

[ericstj]

@gewarren let me know once you're done looking at this and I will merge. After that we need another intellisense build, ingest that into 10.0, then another undocumented API report, and file the issues.

[gewarren]

LGTM