C# - 自建 SDK 的 API 文档

在代码中添加 API 文档

用户在使用类库时，通常需要通过 VS 的 Intellisense 或 F12 反编译查看 API 的注释，借助这些注释来了解如何使用 API。在 C# 源文件中，可以通过编写由三斜杠表示的特殊注释字段，在代码中建立类库所需的 API 文档。注释字段包含用于描述其下方代码块的 XML 元素，XML 元素为 API 文档提供了结构化的格式，便于编译器等工具的解析。例如：

/// <summary>
/// Function does an important thing.
/// </summary>
/// <returns>The result.</returns>
public string DoSomething {}

生成 API 文档的 XML 文件

GenerateDocumentationFile 属性控制编译器是否为库生成 XML 文档文件。 将此属性设置为 true，编译器将在源代码中找到包含 XML 标记的所有注释字段，并根据这些注释创建 XML 文档文件。生成的 XML 文件会放置在与程序集相同的输出目录中，并具有相同的文件名（但扩展名为 .xml）。

启用此选项后，编译器将为项目中所有声明为公开可见但且没有 XML 文档注释的成员，生成 CS1591 警告。

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

类库设定为引用程序集

相较实现程序集（Implementation assemblies），设定类库为引用程序集（Reference assemblies），可以仅暴露声明为公开可见的成员，隐藏私有实现。

例如数据结构、接口协议定义的类库，没有具体需要加载执行的程序集，适合使用此设定。

发布类库

连带着 XML 文档文件，与 DLL 一同发布，两者需在同一目录下。

引用 DLL 时即可看到 API 文档注释。例如：

//
// 摘要:
//     Function does an important thing.
//
// 返回结果:
//     The result.
public string DoSomething {}

参考资料

• C# 指南 - XML 文档注释
• 引用程序集