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 菜单中显示了刚才的凝视内容。
![](http://img1.ph.126.net/tJOU2MeOn560xBzuC_TwVg==/6599301775262142112.jpg)
问题:假设 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+左键,你会看到:
![](http://img0.ph.126.net/1pqIuwNPpJdPVdRf2Bs-RQ==/6619301891769704202.jpg)
问题: 在 Xcode 文本编辑窗体。非常多地方都支持 alt+左键。
请确保你点击在正确的地方。在上面的样例里,你应当在addNumber: 和 toNumber: 两处使用 alt+左键。
你或许不知道,这种方法的实现真的非常恶心。它只能使用非负数作为參数。为了让用户明确这一点,你应当在凝视中加入很多其它的说明。
因此,我们能够在 @return 前面加入一个 @warning 标签。
* @warning Please make note that this method is only good for adding non-negative numbers. |
编译项目,然后使用 alt+剩下。
我们增加 @warning 标签的效果,如以下:
![](http://img1.ph.126.net/1dLfha5m_I4KVw5_ib_4qw==/6619531689699908713.jpg)