Xcode HeaderDoc 教程（2）

Code Snippets，让一切变得更简单:

这真的非常easy，不是吗？但还能更简单一些吗？

本站以前介绍过 code snippets。请看这里。

Code snippets 在 Xcode 中扮演着无名英雄的角色。一个snippet 是一个能够重用的代码块（存储在 snippet 库中）。Snippets 甚至能够包括一些须要你去填充的占位符。

这意味着什么？你能够用 snipppet来为你进行文档化。

这真是个不错的注意。

在 MathAPI.h 中。在原有的凝视上面加入下面内容：

/*!  * @discussion <#description#>

  * @param <#param description#>

  * @return <#return description#> 

*/

注意。当你粘贴上述代码时。“<# #>”之间的内容会变成一个token,你能够通过 tab 键在 token 之间来回切换。这就像你编写代码时使用的自己主动完毕功能。

接下来我们使用一个小技巧。

打开 Utilities 面板中的 CodeSnippets Library 检查器窗体，选中这段凝视块，将它拖到 Code Snippet Library 窗体中（从某个 token 比如<#description#>開始拖）:

将弹出一个窗体让你输入 snippet 的某些信息。并以此来创建一个自己主动完毕快捷方式。

你能够在当中编写代码。

依照例如以下形式填写：

随时能够编辑 snippet 的代码或快捷方式。你能够编辑 snippet也能够又一次创建新的 snippet。

要编辑 snippet,点击 Code Snippet Library 中的 snippet，然后点 Edit button。

要想让你的 snippet 生效，首先删除原有凝视，然后将鼠标放到addNumber:toNumber: 方法的 + 号前面,输入doccomment，然后回车，你的 snippet 将自己主动出现。通过 Tab 键在3个 token 间移动，并填充它们。终于完毕的文档化结果例如以下:

/*!  * @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.

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

  * @return The sum of the two numbers passed in. 

*/

当然，第2个 @param 标签和 @warning 标签须要你手动书写，但snippet 还是节省了不少的时间。

你能够继续这样做。

看，文档化什么的都是菜。

Typedefs的文档化

打开 Car.h，在 class 之前另一些东西要文档化。有一个NS_ENUM，即 typedef enum，一个块。几个属性，一个空方法。

先别气馁，这非常easy，分分钟的事情。

还记得 @typedef 标签吗？这个顶级标签略微特殊一点。它能够对typedef enum 或者 typedef struct 之类的东东进行凝视。

依据你凝视的对象的不同。它会包括与定义的类型相关的二级标签。

以 enum 为例，它会包括 @constant 标签。用于每一个常量（对于struct，则会是 @field 标签）。

找到 enum OldCarType。

它包括两个常量。是用于古典汽车的。在typedef 声明之上。将原来的凝视替换为：

/*!  * @typedef OldCarType

  * @brief A list of older car types.

  * @constant OldCarTypeModelT A cool old car.

  * @constant OldCarTypeModelA A sophisticated old car.

  */

typedef enum {

OldCarTypeModelT,

OldCarTypeModelA

} OldCarType;

编译，然后在 OldCarType 上使用alt+左键。

你会看到 @brief 标签的内容出现了。

如今，在 OldCarTypeModelA 上 alt+左键。看到你的凝视了吗?

悲剧发生了。

别操心，你仍然能够找回忆要的东西——我们必须要正确的东西放在正确的位置上。

在 enum 中加入例如以下凝视：

But fear not, you canstill get your information where you need it - we've got the trusty tripleforward slash in our tool belt. Add the comments to the enum like you see here:

typedef enum {

/// A cool, old car.

OldCarTypeModelT,

/// A sophisticated older car.

OldCarTypeModelA

} OldCarType;

编译，alt+左键。就能看到你的凝视了。

在这个类中仅仅有一个 NS_ENUM，因此接下来有你自己进行文档化。

常量已经凝视了。你仅仅要对整个NS_ENUM 进行一个整体的凝视就能够了。

/*!  * @typedefCarType

  * @brief Alist of newer car types.

  * @constantCarTypeHatchback Hatchbacks are fun, but small.

  * @constantCarTypeSedan Sedans should have enough room to put your kids, and your golfclubs

  * @constantCarTypeEstate Estate cars should hold your kids, groceries, sport equipment,etc.

  * @constantCarTypeSport Sport cars should be fast, fun, and hard on the back.

*/

注意:这个enum 是通过宏来声明的，悲催的 Xcode 不能全然支持和 typedef enum 一样的文档特性，尽管NS_ENUM 实际上是声明 enums 的推荐的方法。或许这一点将来会改变。但眼下还没有，仅仅能徒呼奈何。

如今来文档化 CarType 属性。

/// Indicates the kind of car as enumerated in the "CarType" NS_ENUM

@property (nonatomic, assign) CarType carType;

编译，在 carType 变量名上 alt+左键。

仍然是 Car.h，继续文档化 typedef block。

见下：

/*!  * @brief A block that makes the car drive.

  * @param distance The distance is equal to a distance driven when the block is ready to execute. It could be miles, or kilometers, but not both. Just pick one and stick with it. ;]  

*/ typedef void(^driveCompletion)(CGFloat distance);

typedef block 的文档化和之前的并无多少不同。它包括了：

• 一个 @brief 标签，简单说明了一下这个块的作用。
• 一个 @param 标签，说明调用块时须要传递的參数。

加入格式化代码到文档中

有时。对于程序猿来说。告诉他怎样使用一个方法会更好。

比如。Car 类的 driveCarWithComplete: 方法。

这种方法以块作为參数，由于块对于新手来说一般比較困难，因此最好是告诉程序猿怎样使用这种方法。

这须要使用 @code 标签。在 driveCarWithCompletion方法声明之前加入例如以下内容：

/*!  * @brief The car will drive, and then execute the drive block

  * @param completion A driveCompletion block

  * @code [car driveCarWithCompletion:^(CGFloat distance){      NSLog(@"Distance driven %f", distance);  }];

  */

编译，在方法名上使用alt+左键。例如以下图所看到的。

检查文档

你学会了怎样加入凝视，假设 Xcode 能帮你检查你的工作，就像Xcode会自己主动检查代码中的语法错误。那岂不是更好？有一个好消息，Clang 有一个标志。叫做“CLANG_WARN_DOCUMENTATION_COMMENTS”,能够用于检查 HeaderDoc 格式的凝视。

打开 DocumentationExamples的项目设置，点击 Build Settings，找到 DocumentationComments, 将值设置为 YES。