dotnet-xml-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dotnet-xml-docs

XML documentation comments for .NET: all standard tags (

<summary>

<param>

<returns>

<exception>

<remarks>

<example>

<value>

<typeparam>

<typeparamref>

<paramref>

), advanced tags (

<inheritdoc>

for interface and base class inheritance,

<see cref="..."/>

<seealso>

<c>

and

<code>

), enabling XML doc generation with

<GenerateDocumentationFile>

MSBuild property, warning suppression strategies for internal APIs (

CS1591

<NoWarn>

InternalsVisibleTo

), XML doc conventions for public NuGet libraries, auto-generation tooling (IDE quick-fix

///

trigger, GhostDoc-style patterns), and IntelliSense integration showing XML docs in IDE tooltips and autocomplete.

Version assumptions: .NET 8.0+ baseline. XML documentation comments are a C# language feature available in all .NET versions.

<GenerateDocumentationFile>

MSBuild property works with .NET SDK 6+.

<inheritdoc>

fully supported since C# 9.0 / .NET 5+.

适用于.NET的XML文档注释：包含所有标准标签（

<summary>

、

<param>

、

<returns>

、

<exception>

、

<remarks>

、

<example>

、

<value>

、

<typeparam>

、

<typeparamref>

、

<paramref>

）、高级标签（用于接口和基类继承的

<inheritdoc>

、

<see cref="..."/>

、

<seealso>

、

<c>

和

<code>

）、通过

<GenerateDocumentationFile>

MSBuild属性启用XML文档生成、内部API的警告抑制策略（

CS1591

、

<NoWarn>

、

InternalsVisibleTo

）、公共NuGet库的XML文档约定、自动生成工具（IDE快速修复

///

触发、GhostDoc风格的模板），以及IntelliSense集成（在IDE提示和自动补全中显示XML文档）。

版本说明： 基于.NET 8.0+。XML文档注释是C#语言特性，所有.NET版本均支持。

<GenerateDocumentationFile>

MSBuild属性在.NET SDK 6+中可用。

<inheritdoc>

自C# 9.0 / .NET 5+起完全支持。

Scope

适用范围

Standard XML doc tags (summary, param, returns, exception, remarks, example)
Advanced tags (inheritdoc, see cref, seealso, c, code)
GenerateDocumentationFile MSBuild configuration
Warning suppression strategies for internal APIs (CS1591)
Conventions for public NuGet library documentation

标准XML文档标签（summary、param、returns、exception、remarks、example）
高级标签（inheritdoc、see cref、seealso、c、code）
GenerateDocumentationFile MSBuild配置
内部API的警告抑制策略（CS1591）
公共NuGet库的文档约定

Out of scope

不适用范围

API documentation site generation (DocFX, Starlight) -- see [skill:dotnet-api-docs]
General C# coding conventions and naming standards -- see [skill:dotnet-csharp-coding-standards]
CI/CD deployment of documentation sites -- see [skill:dotnet-gha-deploy]

Cross-references: [skill:dotnet-api-docs] for downstream API documentation generation from XML comments, [skill:dotnet-csharp-coding-standards] for general C# coding conventions, [skill:dotnet-gha-deploy] for doc site deployment.

API文档站点生成（DocFX、Starlight）——请查看[skill:dotnet-api-docs]
通用C#编码约定和命名规范——请查看[skill:dotnet-csharp-coding-standards]
文档站点的CI/CD部署——请查看[skill:dotnet-gha-deploy]

交叉引用：[skill:dotnet-api-docs] 用于从XML注释生成下游API文档，[skill:dotnet-csharp-coding-standards] 用于通用C#编码约定，[skill:dotnet-gha-deploy] 用于文档站点部署。

Enabling XML Documentation Generation

启用XML文档生成

MSBuild Configuration

MSBuild配置

Enable XML documentation file generation in the project or

Directory.Build.props

xml

<!-- In .csproj or Directory.Build.props -->
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

This generates a

.xml

file alongside the assembly during build (e.g.,

MyLibrary.xml

next to

MyLibrary.dll

). NuGet pack automatically includes this XML file in the package, enabling IntelliSense for package consumers.

在项目或

Directory.Build.props

中启用XML文档文件生成：

xml

<!-- 在.csproj或Directory.Build.props中 -->
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

这会在构建时在程序集旁边生成一个

.xml

文件（例如，

MyLibrary.dll

旁边的

MyLibrary.xml

）。NuGet打包会自动将此XML文件包含在包中，为包使用者提供IntelliSense支持。

Warning Suppression for Internal APIs

内部API的警告抑制

When

GenerateDocumentationFile

is enabled, the compiler emits CS1591 warnings for all public members missing XML doc comments. Suppress warnings selectively for internal-facing code:

Option 1: Suppress globally for the entire project (not recommended for public libraries):

xml

<PropertyGroup>
  <NoWarn>$(NoWarn);CS1591</NoWarn>
</PropertyGroup>

Option 2: Suppress per-file with pragma directives (recommended for mixed-visibility assemblies):

csharp

#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
public class InternalServiceHelper
{
    // This type is internal-facing despite being public
    // (e.g., exposed for testing via InternalsVisibleTo)
}
#pragma warning restore CS1591

Option 3: Use
InternalsVisibleTo
and keep internal types truly internal:

csharp

// In AssemblyInfo.cs or a Properties file
[assembly: InternalsVisibleTo("MyLibrary.Tests")]

csharp

// Mark internal-facing types as internal instead of public
internal class ServiceHelper
{
    // No CS1591 warning -- internal types are not documented
}

Option 4: Treat missing docs as errors for public libraries (strictest):

xml

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <!-- Treat missing XML docs as build errors -->
  <WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors>
</PropertyGroup>

This forces documentation for every public member. Use this for NuGet packages where consumers depend on IntelliSense documentation.

For complete tag examples (summary, param, returns, exception, remarks, example, inheritdoc, see/seealso, comprehensive class example, library conventions), see

examples.md

in this skill directory.

启用

GenerateDocumentationFile

后，编译器会为所有缺少XML文档注释的公共成员发出CS1591警告。可以有选择地抑制面向内部代码的警告：

选项1：在整个项目中全局抑制（不推荐用于公共库）：

xml

<PropertyGroup>
  <NoWarn>$(NoWarn);CS1591</NoWarn>
</PropertyGroup>

选项2：使用pragma指令按文件抑制（推荐用于混合可见性的程序集）：

csharp

#pragma warning disable CS1591 // 缺少公共可见类型或成员的XML注释
public class InternalServiceHelper
{
    // 尽管此类是公共的，但它是面向内部的
    // （例如，通过InternalsVisibleTo暴露用于测试）
}
#pragma warning restore CS1591

选项3：使用
InternalsVisibleTo
并保持内部类型真正为internal：

csharp

// 在AssemblyInfo.cs或Properties文件中
[assembly: InternalsVisibleTo("MyLibrary.Tests")]

csharp

// 将面向内部的类型标记为internal而非public
internal class ServiceHelper
{
    // 不会有CS1591警告——内部类型无需文档
}

选项4：将缺少文档视为公共库的错误（最严格）：

xml

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <!-- 将缺少XML文档视为构建错误 -->
  <WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors>
</PropertyGroup>

这会强制为每个公共成员编写文档。适用于依赖IntelliSense文档的NuGet包。

完整的标签示例（summary、param、returns、exception、remarks、example、inheritdoc、see/seealso、完整类示例、库约定），请查看此技能目录中的

examples.md

。

Agent Gotchas

Agent注意事项

Always enable
<GenerateDocumentationFile>
for public libraries -- without it, NuGet consumers get no IntelliSense documentation. Add it to
```
Directory.Build.props
```
to apply across all projects in a solution.
Use
<inheritdoc />
for interface implementations and overrides -- do not duplicate documentation text between an interface and its implementation. Duplication causes maintenance drift.
Do not suppress CS1591 globally for public NuGet packages -- global suppression via
```
<NoWarn>CS1591</NoWarn>
```
hides all missing documentation warnings. Use per-file
```
#pragma
```
suppression for intentionally undocumented types, or make internal types truly
```
internal
```
.
Use
<see cref="..."/>
for all type references, not bare type names --
```
<see cref="Widget"/>
```
enables IDE navigation and is validated at build time. Bare text "Widget" is not linked and can become stale if the type is renamed.
Use
<see langword="null"/>
instead of bare
null
in documentation text -- this renders with proper formatting in IntelliSense and API doc sites. Same applies to
```
true
```
,
```
false
```
, and other C# keywords.
<inheritdoc>
resolves at build time, not design time -- some older IDE versions may show "Documentation not found" for
```
<inheritdoc>
```
in tooltips. The documentation is correctly resolved in the generated XML file and in API doc sites.
XML doc comments must use
<
and
>
for generic type syntax in prose -- but
```
<see cref="..."/>
```
handles generics automatically. Use
```
<see cref="List{T}"/>
```
(curly braces), not
```
<see cref="List&lt;T&gt;"/>
```
.
In
<code>
blocks, use
<
and
>
for angle brackets -- XML doc comments are XML, so
```
<
```
and
```
>
```
in code examples must be escaped. Alternatively, use
```
<![CDATA[...]]>
```
to avoid escaping.
Do not generate API documentation sites from XML comments -- API doc site generation (DocFX, OpenAPI-as-docs) belongs to [skill:dotnet-api-docs]. This skill covers the XML comment authoring side only.
Document cancellation tokens with a single standard line -- use "A token to cancel the asynchronous operation." for all
```
CancellationToken
```
parameters. Do not over-document the cancellation pattern.

始终为公共库启用
<GenerateDocumentationFile>
——如果不启用，NuGet使用者将无法获得IntelliSense文档。将其添加到
```
Directory.Build.props
```
以应用于解决方案中的所有项目。
对接口实现和重写使用
<inheritdoc />
——不要在接口及其实现之间重复文档文本。重复会导致维护偏差。
不要为公共NuGet包全局抑制CS1591——通过
```
<NoWarn>CS1591</NoWarn>
```
全局抑制会隐藏所有缺少文档的警告。对有意不文档化的类型使用按文件
```
#pragma
```
抑制，或者将内部类型真正标记为
```
internal
```
。
对所有类型引用使用
<see cref="..."/>
，而不是裸类型名称——
```
<see cref="Widget"/>
```
支持IDE导航，并在构建时进行验证。裸文本“Widget”没有链接，且在类型重命名后可能失效。
在文档文本中使用
<see langword="null"/>
代替裸
null
——这会在IntelliSense和API文档站点中正确格式化。同样适用于
```
true
```
、
```
false
```
和其他C#关键字。
<inheritdoc>
在构建时解析，而非设计时——一些旧版IDE可能在提示中显示“未找到文档”，但生成的XML文件和API文档站点中会正确解析文档。
在XML文档注释的 prose 中，泛型类型语法必须使用
<
和
>
——但
```
<see cref="..."/>
```
会自动处理泛型。使用
```
<see cref="List{T}"/>
```
（大括号），而非
```
<see cref="List&lt;T&gt;"/>
```
。
在
<code>
块中，对尖括号使用
<
和
>
——XML文档注释是XML，因此代码示例中的
```
<
```
和
```
>
```
必须转义。或者，使用
```
<![CDATA[...]]>
```
避免转义。
不要从XML注释生成API文档站点——API文档站点生成（DocFX、OpenAPI-as-docs）属于[skill:dotnet-api-docs]。本技能仅涵盖XML注释编写部分。
用单行标准语句记录取消令牌——对所有
```
CancellationToken
```
参数使用“用于取消异步操作的令牌。”。不要过度记录取消模式。