C# – 自建 SDK 的 API 文档

  • C# – 自建 SDK 的 API 文档已关闭评论
  • 92 次浏览
  • A+
所属分类:.NET技术
摘要

用户在使用类库时,通常需要通过 VS 的 Intellisense 或 F12 反编译查看 API 的注释,借助这些注释来了解如何使用 API。在 C# 源文件中,可以通过编写由三斜杠表示的特殊注释字段,在代码中建立类库所需的 API 文档。注释字段包含用于描述其下方代码块的 XML 元素,XML 元素为 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 {} 

参考资料