【风宇冲】Unity3D教程宝典之 C#代码注释规范及文档生成

素颜马尾好姑娘i 2022-03-12 14:19 293阅读 0赞

### 原创文章如需转载请注明：转载自[风宇冲Unity3D教程学院][Unity3D] ###

C\#代码注释规范及文档生成

在使用c\#进行Unity3D游戏开发中，良好的注释和文档能让开发更有效率，条理更清晰。

本讲分为两个部分：

一：编写注释

二: 生成文档

**                         编写注释**

开发注释是 // 帮助拓展代码  
使用注释是 /// 帮助使用代码

开发注释：辅助开发，对变量或者函数等代码的后续开发做的注释。

例如，你定义了一个私有变量 private int coins; 不打算让外部访问该变量。但在开发过程中，需要一些提示。

//金币的数量

private int  coins ;

使用注释：帮助使用，主要是对使用变量或函数等代码的使用调用做的注释。

例如上面的coins变量，我们打算让外部能访问。那么代码是public int coins; 在这段代码前输入///

则Mono会自动根据变量名生成如下注释，summary是对下方代码的总结

1. /// <summary>
2. /// The coins.
3. /// </summary>
4. public int coins;

之后你可以自己添加注释如

1. /// <summary>
2. /// 金币总数
3. /// </summary>
4. public int coins;

或者按行输入文本， <para></para> 代表一行

1. /// <summary>
2. /// <para>金币数</para>
3. /// <para>可以当钱花</para>
4. /// </summary>
5. public int coins;

函数也是同样的写法。

有函数如下

1.  public void UseCoins(int number)
2.  \{
3.  \}

在函数前输入///   , 得到如下，其中  < param   name ='number'> </param>代表一个参数

1. /// <summary>
2. /// Uses the coins.
3. /// </summary>
4. /// <param name='number'>
5. /// Number.
6. /// </param>
7. public void UseCoins(int number)
8. \{
9. \}

这么写的好处是：

1.调用时弹出注释，如下

[![【风宇冲】Unity3D教程宝典之 C\#代码注释规范及文档生成][Unity3D_wbr_C]][Unity3D_wbr_C_Unity3D_wbr_C]

2.能根据该格式的注释自动生成文档

** **

**                      生成文档**

当代码按上面介绍的///格式写了注释后，就可以自动生成文档了。这两天，风宇冲寻找最佳方生成Unity3d代码帮助文档的方法。

尝试了3种方法： 
(1)Mono:Mono提供的方法步骤太繁琐,还要敲指令。放弃。 
(2)Visual Studio + Sandcastle Help File Builder 
这个方法还算可以，步骤稍麻烦，而且Sandcastle Help File Builder缺点比较多，如类必须在命名空间里（unity3d 4.0以上才支持MonoBehaviour的继承函数放在命名空间里），慢，功能不完善等。 
做法： 
    把代码和UnityEngine.dll等库拖进Visual Studio,然后用VS build。 
    之后用Sandcastle Help File Builder载入生成的XML，生成文档。 
(3)Doxgen: 支持图表，类可以不在命名空间里。不支持js。跨平台。 
最后，风宇冲找到了最适合Unity3d的文档生成工具 - Doxgen。 
 
                                                                      **Doxgen使用方法** 
 
下载后打开， 
(1)设置如下图 
[![【风宇冲】Unity3D教程宝典之 C\#代码注释规范及文档生成][Unity3D_wbr_C 1]][Unity3D_wbr_C_Unity3D_wbr_C 1] 
 
(2)设置图表如下。 
[![【风宇冲】Unity3D教程宝典之 C\#代码注释规范及文档生成][Unity3D_wbr_C 2]][Unity3D_wbr_C_Unity3D_wbr_C 2] 
 
 
(3)去掉路径前缀。（该路径会显示在文档页面的左下角） 
例： 
代码路径  D:\\My Documents\\namespaceTest\\Assets\\scripts\\GUI 
则裁剪路径填 D:/My Documents/namespaceTest/Assets/scripts 
[![【风宇冲】Unity3D教程宝典之 C\#代码注释规范及文档生成][Unity3D_wbr_C 3]][Unity3D_wbr_C_Unity3D_wbr_C 3] 
 
(4)生成文档。 
(5)查看文档。

可以点击按钮Show HTML output按钮，或者直接打开本地网页

保存的文件夹->html文件夹->index.html

[![【风宇冲】Unity3D教程宝典之 C\#代码注释规范及文档生成][Unity3D_wbr_C 4]][Unity3D_wbr_C_Unity3D_wbr_C 4] 
 
(6)最后 点击File->Save 保存配置文件。该文件可以用来读取配置，也可以跨平台使用。 
 
PS:MAC的osx系统下，Doxygen的使用方法类似 
 
最终效果：

[![【风宇冲】Unity3D教程宝典之 C\#代码注释规范及文档生成][Unity3D_wbr_C 5]][Unity3D_wbr_C_Unity3D_wbr_C 5]

[Unity3D]: http://blog.sina.com.cn/lsy835375
[Unity3D_wbr_C]: http://s6.sinaimg.cn/mw690/47113292td3e9b685ac35&690
[Unity3D_wbr_C_Unity3D_wbr_C]: /images/20220312/b715bd55885b40da8ebbae713517716a.png
[Unity3D_wbr_C 1]: http://s8.sinaimg.cn/mw690/47113292td21118ecbd67&690
[Unity3D_wbr_C_Unity3D_wbr_C 1]: /images/20220312/eb55c11db8e84c789cb6ee203fa558c8.png
[Unity3D_wbr_C 2]: http://s14.sinaimg.cn/mw690/47113292td21118c3eadd&690
[Unity3D_wbr_C_Unity3D_wbr_C 2]: /images/20220312/8e7fe790ba5f45bfaf13c2fd8f4cabd6.png
[Unity3D_wbr_C 3]: http://s13.sinaimg.cn/mw690/47113292td211190be4bc&690
[Unity3D_wbr_C_Unity3D_wbr_C 3]: /images/20220312/49d137dbb1734bfdae0ce36b5d308d18.png
[Unity3D_wbr_C 4]: http://s13.sinaimg.cn/mw690/47113292t7b681c213d1c&690
[Unity3D_wbr_C_Unity3D_wbr_C 4]: /images/20220312/69598228d2b1470dbdb6d8d2cb172eed.png
[Unity3D_wbr_C 5]: http://s1.sinaimg.cn/mw690/47113292td3e9b4d989b0&690
[Unity3D_wbr_C_Unity3D_wbr_C 5]: /images/20220312/a7a3e2a4d4d2427299a427c26f70ff94.png