C# XML注释需以///开头紧贴声明上方，配合和等标签，并在.csproj中启用true才能生成XML文档文件。
XML注释怎么写才能被编译器识别
C# 编译器只认以 /// 开头的行，且必须紧贴在类型或成员声明上方（中间不能空行）。它不解析普通 // 或 /* */ 注释。
常见错误是写了注释但没加第三个斜杠，或者在类定义和注释之间插了空白行——这两种情况都会导致 xml 文件里对应项为空或完全缺失。
-
///是必需的，缺了会警告 CS1591描述方法用途 -
中的name必须和参数名完全一致（区分大小写） -
void方法建议补全，否则生成文档时返回值栏为空 - 支持
被大多数工具默认提取
如何让 MSBuild 输出 XML 文档文件
仅写注释没用，必须开启编译器的 XML 文档生成功能，否则 .xml 文件根本不会产生。
在项目文件（.csproj）中添加或确认以下配置项：
true
这是 .NET SDK 风格项目的推荐方式。旧式项目需手动设
- 生成的 XML 文件默认和程序集同名，放在输出目录（如
bin/Debug/net8.0/MyLib.xml） - 若项目含多个 TargetFramework，每个框架都会生成独立的 XML 文件
- 未启用该选项时，即使写了完整注释，
dotnet build也不会输出任何 XML —— 这是新手最常卡住的点
用 DocFX 或 SharpDoc 生成 HTML API 文档
MSBuild 生成的 XML 是原始数据，要变成可浏览的网页，得靠外部工具。DocFX 是微软官方维护的主流选择；SharpDoc 更轻量，适合快速预览。
以 DocFX 为例，初始化后关键配置在 docfx.json 的 metadata 段落：
"metadata": [
{
"src": [{ "files": ["../MyLib.csproj"] }],
"dest": "api",
"properties": { "TargetFramework": "net8.0" }
}
]- 确保
src.files指向的是.csproj，不是 DLL 或 XML 文件——DocFX 会自己调用编译器读取 XML - 如果项目依赖其他 NuGet 包，需在
properties中加"RestoreSources"或提前运行dotnet restore - 生成失败常见报错：
Unable to locate the metadata source，基本是路径写错或没生成 XML；Could not load file or assembly多因 TargetFramework 不匹配
为什么 Visual Studio IntelliSense 不显示你的注释
即使 XML 文件已生成，IntelliSense 仍不提示，大概率是因为引用方式不对。
如果你的类库被另一个项目通过 .xml 文件。
但如果用的是 .xml 文件，并打包进 lib/ 目录下（例如 lib/net8.0/MyLib.xml）。
- SDK 项目默认会把 XML 打进 NuGet，但需确认
false - 手动打包时漏掉 XML，或用
nuget pack而非dotnet pack，都可能导致消费者看不到注释 - 检查方法：解压
.nupkg文件，看里面有没有对应路径的 XML —— 这是最直接的验证手段
XML 注释本身简单，真正卡住人的永远是生成链路上某个环节没对齐：编译开关、项目引用方式、NuGet 打包结构、工具配置路径……每一步都得实打实验证输出是否存在，而不是“应该有”。
