C# - 自建 SDK 的 API 文档

非虹

在代码中添加 API 文档

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

1. /// <summary>
2. /// Function does an important thing.
3. /// </summary>
4. /// <returns>The result.</returns>
5. public string DoSomething {}

复制代码

生成 API 文档的 XML 文件

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

1. <PropertyGroup>
2.   <GenerateDocumentationFile>true</GenerateDocumentationFile>
3. </PropertyGroup>

复制代码

类库设定为引用程序集

相较实现程序集（Implementation assemblies），设定类库为引用程序集（Reference assemblies），可以仅暴露声明为公开可见的成员，隐藏私有实现。
例如数据结构、接口协议定义的类库，没有具体需要加载执行的程序集，适合使用此设定。
发布类库

连带着 XML 文档文件，与 DLL 一同发布，两者需在同一目录下。
引用 DLL 时即可看到 API 文档注释。例如：

1. //
2. // 摘要:
3. //     Function does an important thing.
4. //
5. // 返回结果:
6. //     The result.
7. public string DoSomething {}

复制代码

参考资料

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

来源:https://www.cnblogs.com/txrock/archive/2023/10/27/17791189.html
免责声明：由于采集信息均来自互联网，如果侵犯了您的权益，请联系我们【E-Mail:cb@itdo.tech】 我们会及时删除侵权内容，谢谢合作！