dotnet / dotnet/dotnet-api-docs

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

Open
#10,722 3 comments 0 reactions 1 assignee Claimed by @gewarren View on GitHub
:pushpin: seQUESTered :world_map: mapQUEST area-Meta doc-enhancement Pri1 untriaged
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

Copilot instructions for backporting docs to /// in dotnet/runtime:

**XML Documentation Backport Process:**

1. **Source**: Extract XML from https://github.com/dotnet/dotnet-api-docs/blob/main/xml/[Namespace]/[Type].xml

2. **.NET Framework-specific remarks/docs/links**: Remove any .NET Framework-specific remarks/docs/links.

3. **Remarks for unsupported .NET versions**: Remove and discard.

4. **Remarks**: Backport all `` from XML, including notes and para elements. Convert XML entities (`<` → `<`, `>` → `>`).

5. **Code examples**:
- Create a separate `.Examples.cs` file in `src/libraries/[Library]/samples/[Namespace]/[Type].Examples.cs`
- Use `#region RegionName` blocks for each example
- Reference from docs: `` (or, in Markdown, `[!code-csharp[]([relativepath]/[Type].Examples.cs#[region])]`)
- Use relative paths from source file to samples directory (e.g., `../../../../samples/...`)

6. **Avoid duplication**: Only document in shared/CoreCLR files, not in Mono-specific partials unless behavior differs

7. **src vs. ref**: Documentation should go in the source implementation files, not the ref assembly

8. **Multiple implementations**: For assemblies with multiple runtime-specific, OS-specific, or architecture-specific implementations. Jan's suggestion is to add partial methods to the neutral file and keep the documentation there.

9. **XML syntax conventions**:
- Use `` for keywords (`null`, `true`, `false`, `void`)
- Use `` for types and members
- Use `code` tags for inline code elements, NOT backticks
- Use `` for notes
- Use `` for paragraph breaks in remarks

10. **Very lengthy remarks**: If remarks are very long, still port them to the dotnet/runtime repo, but put them in a separate "docs" directory and then link there from the ///.

11. Once all the public types in a given assembly have been documented, remove `false` from its .csproj file.

To be done separately:

- Disable the Edit functionality on learn.microsoft.com by setting `open_to_public_contributors` to `false` for the namespace (or individual types if the assembly doesn't encompass the entire namespace) [here](https://github.com/dotnet/dotnet-api-docs/blob/e50d1863acf6da5affec9b315ba2ed88d12274e3/docfx.json#L165).
- Similarly to the previous bullet point, update the GitOps policy that aims to prevent any docs-repo edits to the namespace (or individual types if the assembly doesn't encompass the entire namespace) [here](https://github.com/dotnet/dotnet-api-docs/blob/main/.github/policies/disallow-edits.yml).
- If the assembly *doesn't* ship as part of the shared framework (it's part of the shared framework if it's listed [here](https://github.com/dotnet/runtime/blob/4b96b748e706d163622052e6219d3f78cf53e687/src/libraries/NetCoreAppLibrary.props#L28)), i.e. it ships as a standalone NuGet package, remove the package name from [this list](https://github.com/dotnet/docs-tools/blob/e32545768272917a7420881026c82488fce17d67/PackageIndexer/PlatformPackageDefinition.cs#L28).
- If the assembly *does* ship as part of the shared framework, add it [to the list of XML files](https://microsoft.sharepoint.com/teams/DotNETandWebDevContent/_layouts/15/Doc.aspx?sourcedoc={0a811e54-964b-4322-83c0-52530ce1ba85}&action=edit&wd=target%28API%20generation%20process.one%7C8127a7eb-32d2-4027-b369-951d4527137a%2FAPI%20docs%20generation%20process%7C7b904331-cd68-4e7f-8605-504cbbac7944%2F%29&wdorigin=NavigationUrl) to push to the binaries repo for docs CI pipeline ingestion.

---
[Associated WorkItem - 97017](https://dev.azure.com/msft-skilling/Content/_workitems/edit/97017)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.