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 标签以 @ 符号开头。然后是keyword，然后是一个空格。最后才是对应的文本（比如 @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 标签的效果，如以下：