dotnet-api-docs icon indicating copy to clipboard operation
dotnet-api-docs copied to clipboard

Reconcile dotnet-api-docs descriptions with dotnet/runtime ///

Open gewarren opened this issue 2 years ago • 2 comments

  1. Generate IntelliSense XML files for each namespace in dotnet/runtime (see instructions below) - use a specific tag so all APIs already exist in dotnet-api-docs.
  2. Copy the IntelliSense XML files to a branch in the binaries repo.
  3. Consider (temporarily) reformatting all the ECMAXML files if this generates less noise in the IntelliSense files.
    • CLI: find . -name "*.xml" -type f | xargs -I'{}' xmllint --output '{}' --format '{}' (but this tool might do unwanted things)
    • VS Code extension (Red Hat XML) with xml.format.maxlinewidth set to 0 (disable) - sample PR is here.
  4. Use the doc comment resolver tool in dotnet/docs-tools to update the IntelliSense files with any conflicting text from the dotnet-api-docs repo.
  5. Open each file that was modified and resolve all the conflicts.
  6. Run the CI pipeline to import the doc comments.
  7. Use https://github.com/dotnet/api-docs-sync/tree/main/src/PortToTripleSlash to port the comments back to ///.
  8. Open PRs in the dotnet/runtime repo.

Related items:

dotnet/runtime#44969 User Story 633174: [.NET] Partially import doc comments - Boards (azure.com)


Associated WorkItem - 97017

gewarren avatar Jun 02 '23 21:06 gewarren

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

ghost avatar Dec 04 '24 19:12 ghost

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

ghost avatar Dec 04 '24 19:12 ghost