Xcode HeaderDoc 教程（1）

原文： http://www.raywenderlich.com/66395/documenting-in-xcode-with-headerdoc-tutorial

学习如何从代码中生成文档！

Xcode 5 和 iOS7 发布时，大多数人可能没有注意到 HeaderDoc。

HeaderDoc 是一个命令行工具，允许你从代码中自动生成格式良好的HTML 文档——当然，注释必须是用指定的格式提供的。

另外，Xcode 还会在 quick look 面板中以 HeaderDoc风格显示你的注释。

通过本教程，你将学习：

1. 如何书写 HeaderDoc 风格的注释
2. 如何在 Xcode 中预览文档
3. 如何生成 HTML 文档
4. 如何使用 VVDocumenter-Xcode(一个易于使用的第3方文档制作工具)

让我们快点开始吧!

开始

下载本教程中用到的 示例项目,build & run。

这个简单的示例程序只包含了两个类：

• Car: 包含几个属性及一个 “drive” 方法以及一个 completion 块。
• MathAPI: 包含了1个方法，用于累加两个数。

现在，这两个类还没有任何注释。我们将演示如何通过 HeaderDoc 为这两个类创建文档。

HeaderDoc 注释

HeaderDoc 可以从命令行中运行，也可以通过 Xcode 运行。它扫描文件中以某种格式书写的注释,包括这3种形式：

注释 1:

/// Your documentation comment will go here

注释 2:

/**  * Your documentation comment will go here  */

注释 3:

/*!  * Your documentation comment will go here  */

这些注释和普通注释没有什么不同，除了：

注释1，多了一个 /

注释2，多了一个 *

注释3，多了一个 !

注意：在注释2和注释3中，在每一行开头都会有一个额外的*，直至结尾的 */。这仅仅是为了美观，而不是必须的。

这3中语法在 Xcode 中都将产生同样的文档。

为了便于理解，本文将采用下列规则：

• 对于较长的注释块，我们使用 /*！注释。
• 对于单行注释，我们使用 ///。

HeaderDoc 标签

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

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

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

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

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

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

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

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

属性的文档化

首先开始对属性进行文档化。

用 Xcode 打开DocumentationExamples 项目, 打开ViewController.h,你会发现有两个属性需要文档化。在 car 属性的十分，加入一行注释:

/*!  * @brief The ViewController class' car object.  */ @property (nonatomic) Car *car;

编译项目。编译结束，按住 alt/option 键，点击 car 变量名。你将看到pop 菜单中显示了刚才的注释内容。

问题:如果 pop 菜单中未显示注释内容，可能编译尚未结束。等编译结束，重启 Xcode，然后重试。

一切如此简单。请你试着对另一个属性进行注释。例如：这个属性是汽车的名字，建议有趣一点等等。

 

/*!  *@brief A Title for the car. Make it funny. Seriously.  */

 

在完成文档化之前，可以在 Xcode 中以另一种方法预览文档。切换到Utitlities 面板的 Quick Help 检查器窗口。点击 car 变量名，通过 Quick Help,你将看到如下效果：

现在，有两个类需要进行文档化： MathAPI和Car。

方法的文档化

MathAPI包含一个方法需要文档化。打开MathAPI.h,找到addNumber:toNumber:。

这个方法有两个参数及一个返回值。因此需要一个 @description 标签、两个@param标签，以及一个@return 标签，如下面所示：

/*!  * @discussion A really simple way to calculate the sum of two numbers.       * @param firstNumber An NSInteger to be used in the summation of two numbers      * @param secondNumber The second half of the equation.      * @return The sum of the two numbers passed in.  */ + (NSInteger)addNumber:(NSInteger)firstNumber toNumber:(NSInteger)secondNumber;

编译，通过 alt+左键，你会看到：

问题: 在 Xcode 文本编辑窗口，很多地方都支持 alt+左键。请确保你点击在正确的地方。在上面的例子里，你应当在addNumber: 和 toNumber: 两处使用 alt+左键。

你也许不知道，这个方法的实现真的很恶心。它只能使用非负数作为参数。为了让用户明白这一点，你应当在注释中添加更多的说明。因此，我们可以在 @return 前面加入一个 @warning 标签。

* @warning Please make note that this method is only good for adding non-negative numbers.

编译项目，然后使用 alt+左键。我们添加的 @warning 标签效果如下：