From 3091206154d242715fd14d171c7d4fe6c63c42c9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 1 Nov 2025 19:56:08 +0000
Subject: [PATCH 01/10] Add documentation workflow clarifications to guidelines
Co-authored-by: jkotas <6668460+jkotas@users.noreply.github.com>
---
.../adding-api-guidelines.md | 21 ++++++++++++++++---
docs/coding-guidelines/project-guidelines.md | 2 +-
2 files changed, 19 insertions(+), 4 deletions(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index 473ebf67b7483f..7e659797f78c8a 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -44,12 +44,27 @@ should be added to `net10.0`. [More Information on TargetFrameworks](https://lea
New public APIs must be documented with triple-slash comments on top of them. Visual Studio automatically generates the structure for you when you type `///`.
+[API writing guidelines](https://github.com/dotnet/dotnet-api-docs/wiki)) has information about language and proper style for writing API documentation.
If your new API or the APIs it calls throw any exceptions, those need to be manually documented by adding the `` elements.
-After your change is merged, we will eventually port them to the dotnet-api-docs repo, where we will review them for language and proper style (For more information, see the [API writing guidelines](https://github.com/dotnet/dotnet-api-docs/wiki)).
+After your change is merged, we will eventually port them to the [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repo. Once the dotnet-api-docs change
+is merged, your comments will start showing up in the official API documentation at https://learn.microsoft.com, and later they'll appear in IntelliSense
+in Visual Studio and Visual Studio Code.
-Once the dotnet-api-docs change is merged, your comments will start showing up in the official API documentation at https://learn.microsoft.com, and later they'll appear in IntelliSense in Visual Studio and Visual Studio Code.
-Once the documentation is official, any subsequent updates to it must be made directly in https://github.com/dotnet/dotnet-api-docs/. It's fine to make updates to the triple slash comments later, they just won't automatically flow into the official docs.
+The rest of the documentation workflow depends on whether the assembly has the `UseCompilerGeneratedDocXmlFile` property set in its project file:
+
+**For libraries without this property (or with it set to `true`, which is the default):**
+- Source comments in this repo are the source of truth for documentation.
+- Triple-slash comments in source code are synced to dotnet-api-docs periodically.
+- More recently introduced libraries typically follow this workflow.
+
+**For libraries with `false`:**
+- The [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repo is the source of truth for documentation.
+- Triple-slash comments in source code are synced to dotnet-api-docs **only once** for newly introduced APIs. After the initial sync, all subsequent documentation
+updates must be made directly in the dotnet-api-docs repo.
+- It's fine to make updates to the triple-slash comments later, they just won't automatically flow into the official docs. Copilot can help with porting the changes
+in triple slash-comments to dotnet-api-docs.
+- Older libraries typically follow this workflow.
## FAQ
diff --git a/docs/coding-guidelines/project-guidelines.md b/docs/coding-guidelines/project-guidelines.md
index f16b945e30adf6..c9be6e151094b2 100644
--- a/docs/coding-guidelines/project-guidelines.md
+++ b/docs/coding-guidelines/project-guidelines.md
@@ -192,7 +192,7 @@ The `UseCompilerGeneratedDocXmlFile` property controls how XML documentation fil
```
-Setting `UseCompilerGeneratedDocXmlFile` to `false` is typically done for stable APIs where manually curated documentation exists that should be preferred over compiler-generated documentation.
+See the [Documentation](adding-api-guidelines.md#documentation) section in the API guidelines for more details about the documentation workflow.
If a project sets this to `false` but the Microsoft.Private.Intellisense package doesn't have documentation for the assembly, a warning is shown suggesting to remove the property to let the compiler generate the file.
From 7fd18d2bc6791de94b7289951919c3a954f42055 Mon Sep 17 00:00:00 2001
From: Jan Kotas
Date: Sat, 1 Nov 2025 14:13:59 -0700
Subject: [PATCH 02/10] Update docs/coding-guidelines/adding-api-guidelines.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
docs/coding-guidelines/adding-api-guidelines.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index 7e659797f78c8a..7698b715af3f4a 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -44,7 +44,7 @@ should be added to `net10.0`. [More Information on TargetFrameworks](https://lea
New public APIs must be documented with triple-slash comments on top of them. Visual Studio automatically generates the structure for you when you type `///`.
-[API writing guidelines](https://github.com/dotnet/dotnet-api-docs/wiki)) has information about language and proper style for writing API documentation.
+[API writing guidelines](https://github.com/dotnet/dotnet-api-docs/wiki) has information about language and proper style for writing API documentation.
If your new API or the APIs it calls throw any exceptions, those need to be manually documented by adding the `` elements.
After your change is merged, we will eventually port them to the [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repo. Once the dotnet-api-docs change
From 85798fc9296facb0f139c9d208623d8bd6e2151f Mon Sep 17 00:00:00 2001
From: Jan Kotas
Date: Sat, 1 Nov 2025 14:14:09 -0700
Subject: [PATCH 03/10] Update docs/coding-guidelines/adding-api-guidelines.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
docs/coding-guidelines/adding-api-guidelines.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index 7698b715af3f4a..6612fa949a71f3 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -63,7 +63,7 @@ The rest of the documentation workflow depends on whether the assembly has the `
- Triple-slash comments in source code are synced to dotnet-api-docs **only once** for newly introduced APIs. After the initial sync, all subsequent documentation
updates must be made directly in the dotnet-api-docs repo.
- It's fine to make updates to the triple-slash comments later, they just won't automatically flow into the official docs. Copilot can help with porting the changes
-in triple slash-comments to dotnet-api-docs.
+in triple-slash comments to dotnet-api-docs.
- Older libraries typically follow this workflow.
## FAQ
From d9a1b7686fc333c7cf1a54255392274f256825b1 Mon Sep 17 00:00:00 2001
From: Jan Kotas
Date: Mon, 3 Nov 2025 11:32:18 -0800
Subject: [PATCH 04/10] Update docs/coding-guidelines/adding-api-guidelines.md
---
docs/coding-guidelines/adding-api-guidelines.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index 6612fa949a71f3..3bb05f7523b010 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -55,7 +55,7 @@ The rest of the documentation workflow depends on whether the assembly has the `
**For libraries without this property (or with it set to `true`, which is the default):**
- Source comments in this repo are the source of truth for documentation.
-- Triple-slash comments in source code are synced to dotnet-api-docs periodically.
+- Triple-slash comments in source code are synced to dotnet-api-docs periodically (every preview).
- More recently introduced libraries typically follow this workflow.
**For libraries with `false`:**
From 5d33dc25571c8bf07b34f44087a893e852684dbb Mon Sep 17 00:00:00 2001
From: Jan Kotas
Date: Mon, 3 Nov 2025 11:41:19 -0800
Subject: [PATCH 05/10] Update docs/coding-guidelines/adding-api-guidelines.md
---
docs/coding-guidelines/adding-api-guidelines.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index 3bb05f7523b010..e5f8d1036cb247 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -64,7 +64,7 @@ The rest of the documentation workflow depends on whether the assembly has the `
updates must be made directly in the dotnet-api-docs repo.
- It's fine to make updates to the triple-slash comments later, they just won't automatically flow into the official docs. Copilot can help with porting the changes
in triple-slash comments to dotnet-api-docs.
-- Older libraries typically follow this workflow.
+- Older libraries typically follow this workflow. Libraries in this mode can work towards a better workflow in the future by using api-docs-sync tool to port back docs to source, then removing the `UseCompilerGeneratedDocXmlFile` property.
## FAQ
From 53c1740e573aad3205fd2d78ef23426bd840931f Mon Sep 17 00:00:00 2001
From: Jan Kotas
Date: Mon, 3 Nov 2025 11:41:52 -0800
Subject: [PATCH 06/10] Update docs/coding-guidelines/adding-api-guidelines.md
---
docs/coding-guidelines/adding-api-guidelines.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index e5f8d1036cb247..19418866f948cc 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -62,7 +62,7 @@ The rest of the documentation workflow depends on whether the assembly has the `
- The [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repo is the source of truth for documentation.
- Triple-slash comments in source code are synced to dotnet-api-docs **only once** for newly introduced APIs. After the initial sync, all subsequent documentation
updates must be made directly in the dotnet-api-docs repo.
-- It's fine to make updates to the triple-slash comments later, they just won't automatically flow into the official docs. Copilot can help with porting the changes
+- It's fine to make updates to the triple-slash comments later to aid local development, they just won't automatically flow into the official docs. Copilot can help with porting the changes
in triple-slash comments to dotnet-api-docs.
- Older libraries typically follow this workflow. Libraries in this mode can work towards a better workflow in the future by using api-docs-sync tool to port back docs to source, then removing the `UseCompilerGeneratedDocXmlFile` property.
From 935dbe6cf87ad2c0e6840ebb35d7227acb512eac Mon Sep 17 00:00:00 2001
From: Jan Kotas
Date: Mon, 3 Nov 2025 11:42:48 -0800
Subject: [PATCH 07/10] Update docs/coding-guidelines/adding-api-guidelines.md
---
docs/coding-guidelines/adding-api-guidelines.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index 19418866f948cc..2027dedb1de5f6 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -47,7 +47,7 @@ New public APIs must be documented with triple-slash comments on top of them. Vi
[API writing guidelines](https://github.com/dotnet/dotnet-api-docs/wiki) has information about language and proper style for writing API documentation.
If your new API or the APIs it calls throw any exceptions, those need to be manually documented by adding the `` elements.
-After your change is merged, we will eventually port them to the [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repo. Once the dotnet-api-docs change
+After your change is merged, we will eventually port them to the [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repo. The tools used for this port live in [api-docs-sync](https://github.com/dotnet/api-docs-sync) repo. Once the dotnet-api-docs change
is merged, your comments will start showing up in the official API documentation at https://learn.microsoft.com, and later they'll appear in IntelliSense
in Visual Studio and Visual Studio Code.
From df6cb738e4625358a6aa27b6d3a88a11a4fc5e27 Mon Sep 17 00:00:00 2001
From: Jan Kotas
Date: Mon, 3 Nov 2025 11:44:18 -0800
Subject: [PATCH 08/10] Update docs/coding-guidelines/adding-api-guidelines.md
---
docs/coding-guidelines/adding-api-guidelines.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index 2027dedb1de5f6..17e94b62d24aef 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -64,7 +64,7 @@ The rest of the documentation workflow depends on whether the assembly has the `
updates must be made directly in the dotnet-api-docs repo.
- It's fine to make updates to the triple-slash comments later to aid local development, they just won't automatically flow into the official docs. Copilot can help with porting the changes
in triple-slash comments to dotnet-api-docs.
-- Older libraries typically follow this workflow. Libraries in this mode can work towards a better workflow in the future by using api-docs-sync tool to port back docs to source, then removing the `UseCompilerGeneratedDocXmlFile` property.
+- Older libraries typically follow this workflow. Libraries in this mode can work towards a better workflow in the future by using api-docs-sync tools to port back docs to source, then removing the `UseCompilerGeneratedDocXmlFile` property.
## FAQ
From 562fb46a4f3871142d3e9dfd8b4ee68ea4506fce Mon Sep 17 00:00:00 2001
From: Jan Kotas
Date: Mon, 3 Nov 2025 14:10:24 -0800
Subject: [PATCH 09/10] Update docs/coding-guidelines/adding-api-guidelines.md
---
docs/coding-guidelines/adding-api-guidelines.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index 17e94b62d24aef..1d529b75e1cfe7 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -62,8 +62,8 @@ The rest of the documentation workflow depends on whether the assembly has the `
- The [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repo is the source of truth for documentation.
- Triple-slash comments in source code are synced to dotnet-api-docs **only once** for newly introduced APIs. After the initial sync, all subsequent documentation
updates must be made directly in the dotnet-api-docs repo.
-- It's fine to make updates to the triple-slash comments later to aid local development, they just won't automatically flow into the official docs. Copilot can help with porting the changes
-in triple-slash comments to dotnet-api-docs.
+- It's fine to make updates to the triple-slash comments later to aid local development, they just won't automatically flow into the official docs. Copilot can help with porting small changes
+in triple-slash comments to dotnet-api-docs. [dotnet-api-docs](https://github.com/dotnet/api-docs-sync/blob/main/docs/PortToDocs.md) tools work better to ports of large changes.
- Older libraries typically follow this workflow. Libraries in this mode can work towards a better workflow in the future by using api-docs-sync tools to port back docs to source, then removing the `UseCompilerGeneratedDocXmlFile` property.
## FAQ
From f677c5b755f12e002faaccbec598578b2f1f2d01 Mon Sep 17 00:00:00 2001
From: Jan Kotas
Date: Mon, 3 Nov 2025 14:11:23 -0800
Subject: [PATCH 10/10] Update docs/coding-guidelines/adding-api-guidelines.md
---
docs/coding-guidelines/adding-api-guidelines.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md
index 1d529b75e1cfe7..9d934a54b5c771 100644
--- a/docs/coding-guidelines/adding-api-guidelines.md
+++ b/docs/coding-guidelines/adding-api-guidelines.md
@@ -63,7 +63,7 @@ The rest of the documentation workflow depends on whether the assembly has the `
- Triple-slash comments in source code are synced to dotnet-api-docs **only once** for newly introduced APIs. After the initial sync, all subsequent documentation
updates must be made directly in the dotnet-api-docs repo.
- It's fine to make updates to the triple-slash comments later to aid local development, they just won't automatically flow into the official docs. Copilot can help with porting small changes
-in triple-slash comments to dotnet-api-docs. [dotnet-api-docs](https://github.com/dotnet/api-docs-sync/blob/main/docs/PortToDocs.md) tools work better to ports of large changes.
+in triple-slash comments to dotnet-api-docs. [PortToDocs](https://github.com/dotnet/api-docs-sync/blob/main/docs/PortToDocs.md) tool works better for ports of large changes.
- Older libraries typically follow this workflow. Libraries in this mode can work towards a better workflow in the future by using api-docs-sync tools to port back docs to source, then removing the `UseCompilerGeneratedDocXmlFile` property.
## FAQ