Skip to content

Net10 docs update - #11847

Merged
ericstj merged 37 commits into
mainfrom
net10-docs-update
Sep 30, 2025
Merged

ericstj merged 37 commits into
mainfrom
net10-docs-update

Conversation

@ericstj

@ericstj ericstj commented Sep 24, 2025 •

Copy link
Copy Markdown
Member

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

@github-actions github-actions Bot added the area-Meta Concerns something that extends across runtime area boundaries, for example, IDisposable. label Sep 24, 2025

@mconnew mconnew left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

WCF api's look good

@ericstj

ericstj commented Sep 25, 2025 •

Copy link
Copy Markdown
Member Author

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

Copy link
Copy Markdown
Collaborator

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

ericstj commented Sep 25, 2025

Copy link
Copy Markdown
Member Author

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?

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>

@gewarren gewarren left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Reviewed through WeakGCHandle.

@gewarren

gewarren commented Sep 26, 2025 •

Copy link
Copy Markdown
Collaborator

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

Preview:
image

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 gewarren left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

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.

Comment thread xml/System/Convert.xml Resolved
Comment thread xml/System/Convert.xml Resolved
Comment thread xml/System/Guid.xml Resolved
@ericstj

ericstj commented Sep 29, 2025 •

Copy link
Copy Markdown
Member Author

The fixup of incorrectly escaped &lt;para and &lt;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

Copy link
Copy Markdown
Collaborator

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

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

@ericstj

ericstj commented Sep 29, 2025

Copy link
Copy Markdown
Member Author

The fixup of incorrectly escaped &lt;para and &lt;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

ericstj commented Sep 29, 2025

Copy link
Copy Markdown
Member Author

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

@ericstj

ericstj commented Sep 29, 2025

Copy link
Copy Markdown
Member Author

The fixup of incorrectly escaped &lt;para and &lt;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

ericstj commented Sep 29, 2025

Copy link
Copy Markdown
Member Author

@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 gewarren left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-Meta Concerns something that extends across runtime area boundaries, for example, IDisposable.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants