如何为 Unity 项目的 C# 代码生成 API 文档

Ylisar · 发表于 2022-11-6 15:32

引子

众所周知，对于无数码农来说，写文档就是一个噩梦。因为有位伟人曾经说过：程序员都很懒。每天不知道有多少码农为了写文档而更加的“聪明绝顶”，写文档尚且如此，那么维护一份持续在更新的 API 文档就更是劳民伤财了。今天我就为大家介绍一个快速生成 C# 代码 API 文档的工具：
对代码的要求

其实，古猿们早就发现了 API 文档维护的巨大工作量，也给出了目前仍为码农们所认可的解决方案：把文档写在注释里。这个解决方案的核心就是：在编码的过程中按照固定格式来写注释；然后再通过工具自动将这些注释提取出来生成 API 文档。
DocFX 就是这样的一个文档自动生成工具。而相应的对于 C# 代码中的注释格式要求是这样的：
/// <summary>
/// 类的注释
/// </summary>
public class MyClass
{
/// <summary>
/// 变量的注释
/// </summary>
public int width;

/// <summary>
/// 获取 width
/// </summary>
/// <returns>width的值</returns>
public int GetWidth()
{
return width;
}

/// <summary>
/// 设置 width 的值
/// </summary>
/// <param name=&#34;w&#34;>新的值</param>
public void SetWidth(int w)
{
width = w;
}
}
这个注释的格式看起来很复杂，但是不要怕，做为世界上最懒的那批人，怎么可能自己手动敲出这个注释格式呢？如果大家是使用 VSCode 进行编码的话，那么安装 C# 插件就可以在敲出 /// 的时候自动生成这个注释格式了（记得把 VSCode 的【Editor: Format On Type】选项打开）。
环境准备

通过在 github 下载 DocFX。这里建议使用稳定版，本文档基于 DocFX v2.59.3 环境编写。
下载完成后解压，并将解压后的文件夹路径添加到电脑的 Path 环境变量中。

为 Unity 工程生成 API 文档

DocFX 的文档中已经有很详细的使用方法了。这里以 Step By Step 的方式为大家介绍一下如何为自己 Unity 项目中的 C# 代码生成 API 文档。

Step1 : 生成 DocFX 的基础工程

在 Unity 项目的根目录下执行命令：
docfx init -q命令完成后，在项目根目录下会生成一个 docfx_project 文件夹：

Step2：修改生成文档的配置 docfx.json。默认情况下 DocFX 中的配置是基于 .csproj 文件来生成文档的。而在 Unity 项目中，我们的代码主要在 Assets 文件夹下，而且 .csproj 工程文件的概念已经被 Unity 弱化了。以我的测试工程为例，C# 代码主要放在 Assets/Scripts 文件夹下，那么 docfx.json 的配置如下（只修改 metadata 中的 src 配置即可，这里就不贴出整个 json 文件了）：

{
  &#34;metadata&#34;: [
{
   &#34;src&#34;: [
      {
      &#34;files&#34;: [
         &#34;**/*.cs&#34;
      ],
      &#34;src&#34; : &#34;../Assets/Scripts&#34;
      }
   ],
   &#34;dest&#34;: &#34;api&#34;,
   &#34;disableGitFeatures&#34;: false,
   &#34;disableDefaultFilter&#34;: false
}
  ]
}

Step3：生成文档。在 Unity 项目根目录下执行命令：

docfx docfx_project\docfx.json --serve注意：
默认的生成配置中，只会生成有 namespace 的 API 文档。
API 文档生成在 docfx_project/_site 文件夹下。
这个命令在生成文档的同时会启动一个本地的网页服务。

Step4：查看文档。在浏览器打开 http://localhost:8080/api/ 即可查看生成的 API 文档，效果如下图：

尾声

为 Unity 项目的 C# 代码生成 API 文档的方法就介绍到这里。其实大家也能看到，DocFX 不止局限于 Unity 项目的使用，理论上所有的 C# 代码都可以用它来生成 API 文档。关键在于要有标准化的注释格式。

		自动登录	找回密码
密码			立即注册

[笔记] 如何为 Unity 项目的 C# 代码生成 API 文档

本帖子中包含更多资源