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.调用时弹出注释，如下

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)设置如下图


(2)设置图表如下。



(3)去掉路径前缀。（该路径会显示在文档页面的左下角）
例：
代码路径  D:\My Documents\namespaceTest\Assets\scripts\GUI
则裁剪路径填 D:/My Documents/namespaceTest/Assets/scripts


(4)生成文档。
(5)查看文档。

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

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

(6)最后 点击File->Save 保存配置文件。该文件可以用来读取配置，也可以跨平台使用。

PS:MAC的osx系统下，Doxygen的使用方法类似

最终效果：