SuperAPI AI 工具集

dotnet-xml-docs

编程与开发

查看项目

更新于 10-16 02:33

技能介绍

用途:为 .NET 项目编写 XML 文档注释,覆盖标准标签(summary、param、returns、exception、remarks、example、value、typeparam、typeparamref、paramref)、高级标签(inheritdoc、see cref、seealso、c、code),以及生成配置与警告抑制策略。

主要能力:启用 XML 文档生成(在 .csproj 或 Directory.Build.props 中设置 <GenerateDocumentationFile>true</GenerateDocumentationFile>,构建时生成与程序集同名的 .xml 文件,NuGet 打包自动包含以支持使用方 IntelliSense);针对内部 API 的 CS1591 警告抑制策略,包括全局 NoWarn、按文件 #pragma warning disable CS1591、使用 InternalsVisibleTo 保持类型为 internal,以及将缺失文档视为错误(WarningsAsErrors 加入 CS1591);公共 NuGet 库的文档约定;IDE 快速修复 /// 触发与 IntelliSense 提示集成。

使用方式:在项目中启用 GenerateDocumentationFile;对接口实现和重写使用 <inheritdoc /> 避免重复;类型引用使用 <see cref="..."/>;关键字使用 <see langword="null"/>;泛型用 <see cref="List{T}"/>;code 块中需转义尖括号或使用 CDATA。

适用场景:公共库与 NuGet 包的文档编写、内部 API 的警告管理、IDE 提示增强。

限制:不涉及 API 文档站点生成(DocFX、Starlight)、通用 C# 编码规范、文档站点 CI/CD 部署。版本假设为 .NET 8.0+ 基线,GenerateDocumentationFile 适用于 .NET SDK 6+,inheritdoc 自 C# 9.0 / .NET 5+ 完全支持。