用途:为 .NET/C# 代码编写 XML 文档注释,涵盖语法、约定与 MSBuild 配置,使生成的 XML 文档文件随程序集发布,并为 IDE 的 IntelliSense 提示与自动补全提供内容。
主要能力:支持标准标签 <summary>、<param>、<returns>、<exception>、<remarks>、<example>、<value>、<typeparam>、<typeparamref>、<paramref>;高级标签 <inheritdoc>(接口与基类继承,支持 cref 与 path 过滤)、<see>、<seealso>、<c>、<code>、<list>。
使用方式:在 .csproj 或 Directory.Build.props 中启用生成: <PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup> 构建时会在程序集旁生成 .xml 文件,NuGet 打包会自动包含,供包使用者获得 IntelliSense。
警告抑制:启用后编译器会对缺少注释的公共成员发出 CS1591。可按需选择:全局 <NoWarn>$(NoWarn);CS1591</NoWarn>;按文件用 #pragma warning disable CS1591 与 restore;用 InternalsVisibleTo 保持类型为 internal;或将 CS1591 加入 WarningsAsErrors 强制公共库补全文档。
适用场景:公共 NuGet 库、需要 IntelliSense 文档的 API、接口与基类实现复用文档。
版本假设:.NET 8.0+ 为基线;XML 文档注释为 C# 语言特性,各 .NET 版本均可用;GenerateDocumentationFile 需 .NET SDK 6+;<inheritdoc> 自 C# 9.0 / .NET 5+ 完整支持。
限制与边界:本技能仅负责 XML 文档注释的编写、约定与 MSBuild 配置;由 XML 注释生成 API 文档站点(DocFX、Starlight)属于 dotnet-api-docs;通用 C# 编码规范属于 dotnet-csharp-coding-standards;文档站点 CI/CD 部署属于 dotnet-gha-deploy。其余细节资料未提供。