Xcode HeaderDoc 过程（1）
原版的： http://www.raywenderlich.com/66395/documenting-in-xcode-with-headerdoc-tutorial
了解如何从代码中生成文档！
Xcode 5 和 iOS7 宣布。数人可能没有注意到 HeaderDoc。
HeaderDoc 是一个命令行工具，同意你从代码中自己主动生成格式良好的HTML 文档——当然，凝视必须是用指定的格式提供的。
另外，Xcode 还会在 quick look 面板中以 HeaderDoc风格显示你的凝视。
通过本教程，你将学习：
- 怎样书写 HeaderDoc 风格的凝视
- 怎样在 Xcode 中预览文档
- 怎样生成 HTML 文档
- 怎样使用 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 标签的效果，如以下：
