翼度科技»论坛 编程开发 .net 查看内容

C# - 自建 SDK 的 API 文档

7

主题

7

帖子

21

积分

新手上路

Rank: 1

积分
21
在代码中添加 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 {}
复制代码
参考资料


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

举报 回复 使用道具