Xcode 生成文档与注释

     软件开发文档是软件开发使用和维护过程中的必备资料。它能提高软件开发的效率，保证软件的质量，而且在软件的使用过程中有指导，帮助，解惑的作用，尤其在维护工作中，文档是不可或缺的资料。

     在ios开放中，我们可以使用系统自带的 HeaderDoc工具生成文档

1、Xcode HeaderDoc 生成文档

在xcode开发中，如果对代码进行正确适当的注释，就可以利用Xcode 自带HeaderDoc工具自动输出一份完整的 HTML项目文档

这里用实例来演示一个 HeaderDoc 生成文档吧～

步骤：（步骤有点小白，大神勿喷！）

1、新建一个名为HeaderDocDemo的xcode项目

2、创建一个名为HeaderDocTest的NSObject类，这里就是要对他生成一份简单的接口文档

01

3、如上图所示，已经下好了一份简单的HeaderDocTest类了，这里就要对它进行生成一份接口文档了。在XCode里点击New,然后点Target给项目添加一个TARGET,其中target选择other -> Aggregate,如下图所示(这里Target我命名为HeaderDocTarget，命名可以随意)

v

4、如下图，点击项目HeaderDocDemo,会发现右边TARGETS下面多出一个HeaderDocTarget，点击Build Phases 再点击“＋”号，出现图中的New Run Script Phase,点击New Run Script Phase生成如下图

5、把以下代码拷贝到代码对话框里

# shell script goes here

mkdir -p headerDoc

find ./HelloPhoneGap/Classes -name \*.h -print | xargs headerdoc2html -o headerDoc

gatherheaderdoc headerDoc

exit 0

注意：代码里的./HelloPhoneGap/Classes是你的类文件的保存的路径，请根据各自情况修改。

6、 在XCode左上角的Scheme里选定刚才生成的Target,然后点Run。
运行以后，在你的项目文件夹里，就会生成一个文档文件夹了。
这些自动生成的文档都是根据你在源代码里写的注释生成的。最后来看下成果

2、Xcode HeaderDoc注释规范

这部分内容很多出自http://www.raywenderlich.com/66395/documenting-in-xcode-with-headerdoc-tutorial

在使用Xcode HeaderDoc生成文档时，并不是任意注释对能生成文档的，比如 //注释  这样的注释就不能生成我们需要的文档，而是需要一定的规范。注释规范也许可能有很多种，这里只介绍我自己平时所用的，如果有好的注释规范，希望大家一起交流

HeaderDoc 在生成文档时，它会扫描文件中以某种格式书写的注释，主要包括三种形式

/// 你要编写的注释

/**   你要编写的注释  */

/*!   你要编写的注释  */

• 对于较长的注释块，我们使用 /*！注释。
• 对于单行注释，我们使用 ///。
• 我一般习惯/*!   */,感觉比较美观吧～

当 HeaderDoc 发现上述3种注释，它就开始寻找其中的HeaderDoc 标签。你可以用 HeaderDoc 标签修饰你的注释。

HeaderDoc 标签以 @ 符号开头，然后是关键字，然后是一个空格，最后才是相应的文本（例如@param attribute 属性注释）。HeaderDoc 标签可以分为两种：

• 顶级标签: 这些标签声明所要注释的对象的类型（例如头部声明、类、方法等等）。

  /*!
   @thisIsAMethod 这是一个方法
   @discussion 允许多行。它不是必须的，仅仅是为了使描述更清晰 啊三等功啊三等功啊三等功啊三等功啊三等功啊三等功啊三等功啊三等功啊三等功啊三等功啊三等功啊三等功
   @param inputStr 输入
   @return 输出
   @auto 出自sb
   */
  - (int)thisIsAMethod:(NSString * _Nullable)inputStr;

  
  
•  二级标签:这些标签才是具体的注释内容。

顶级标签，例如 @typedef，用于表示 typedef 定义的类型，比如枚举、结构体和函数指针。

HeaderDoc 能够根据上下文自动产生顶级标签，因此通常不是必须的。在本教程，这里有一些常用的二级标签:

• @brief: 简单描述你准备文档化的数据的类型，方法等等。
• @abstract: 等于 @brief。
• @discussion: 类似 @abstract 和 @brief，但允许多行。它不是必须的，仅仅是为了使描述更清晰。
• @param: 描述方法、回调或函数的参数名称。
• @return: 描述方法或函数的返回值。（等同于 @result）

完整的标签列表请参见 HeaderDoc User Guide。

为了保持实现文件的整洁，本文中所有注释都书写在头文件中。