Xcode HeaderDoc 教程（3）

打开 MathAPI.h，将第一个 @param 标签的参数名由firstNumber 修改为 thirdNumber,然后编译。

有一个警告发生，甚至提出了修改建议。它不会影响任何事情，但有助于检查文档中的错误。

特殊注释

Xcode 还支持几种特殊注释，对于你或者使用你代码的人非常有用。

打开 Car.m，在 driveCarWithCompletion: 方法中，在调用completion 块之前添加下列注释：

// FIXME: This is broken

// !!!: Holy cow, it should be checked!

// ???: Perhaps check if the block is not nil first?

这里出现了3中注释：

• FIXME: 某个地方需要修正
• !!!: 某个地方需要注意。
• ???: 代码中有问题，或者代码是可疑的。

这些注释不但有助于你浏览代码，而且 Xcode 绘制 Jump Bar 中显示它们。点击Jump Bar，如下图所示：

你将看到这3个注释以粗体显示：

到此，你已经完全掌握了如何对项目进行文档化。花一些时间对项目的其他属性和方法操作一番，并加入一些自己的东西。看看在注释块中改变一些东西或者删除某个标签会发生什么。这将让你明白注释格式如何对文档造成影响的。

用headerdoc2html 创建 HTML文档

文档化是由一个 HeaderDoc 的工具完成的。当 Xcode 安装时，它就已经安装好了。它除了解释你的注释，显示一个弹出菜单以及将注释在Quick Help 中显示之外，还可以在你文档化之后创建 HTML、XML 以及联机帮助手册。

本节介绍 HTML 文件的制作。如果你对用 HeaderDoc 如何创建在线文档感兴趣，请参考HeaderDoc 用户指南.

打开终端，转到 DocumentationExamples 项目目录：

cd /path/to/your/folder

确认该路径下包含了 Xcodeproject  文件(“DocumentationExamples.xcodeproj”)。

然后用下列命令创建 HTML 文档：

headerdoc2html -o ~/Desktop/documentation DocumentationExamples/

此时终端会有许多输出。当创建完毕，返回桌面，出现一个名为documentation 的目录。双击打开，找到 Car_h 目录，打开 index.html。真酷——你拥有了一份精美的文档！

 

解释一下吧。headerdoc2html 脚本有两个参数：

So what justhappened? Well, you ran the headerdoc2htmlscript with 2 options:

• -o ~/Desktop/documentation – 这个参数指定输出的 Html 文件路径——即桌面的 documentation 目录。
• DocumentationExamples/ – 该参数指定要解析的源文件位于 DocumentationExamples 目录（不包含项目目录下的其他目录，因为它们并不包含源代码）

问题: 最新版本headerdoc2html有个问题，用 google chrome打开 index.html后，左边的目录显示不正常，但 Safari打开正常。而且，你会注意到你早先对 carType 属性所做的注释并未显示。看来最新版本的headerdoc2html 不能正确解析 /// 类的注释，你可以使用 /*! 类型的注释代替。

这很酷，但还可以更进一步。除了手动进入到输出目录中进行导航，HeaderDoc还会创建一个主目录索引。返回终端，导航至新建的 documentation 目录，输入：

cd ~/Desktop/documentation

然后输入命令，创建内容索引:

gatherheaderdoc .

gatherheaderdoc自动查找目录，为 . 目录（表示当前目录）创建索引。用 Finder 打开 documentation  目录。你会发现多出一个 masterTOC.html 文件。打开它，它将列出所有已文档化的属性、方法、枚举和块的链接。

你可以将所有 HTML 文件放到 web 服务器上，然后所有人都可以访问你的文档！

VVDocumenter-Xcode

 

最后的内容是 VVDocumenter-Xcode，一个第三方 Xcode插件，它能让你的文档化工作简单至比使用早先介绍的 Code Snippet 更容易。

首先，从 Github 下载插件。

你所需要做的全部工作就是打开项目，然后 Build。它会将插件自动安装到~/Library/ApplicationSupport/Developer/Shared/Xcode/Plug-ins 目录。

然后重启 Xcode。再次打开 DocumentationExamples项目。在 MathAPI.h，删除 addNumber:toNumber 方法的注释块，然后在方法声明上面输入：

///

VVDocumenter-Xcode 将自动创建注释块，包括所有必要的 @param 标签以及自动完成 token。

是不是太给力了？

打开 Car.h，删除 NS_ENUM CarType 的注释，以及每个常量的注释。在NS_ENUM 声明之上，输入：

///

这回，它会在 enum 之上创建 discussion 标签，甚至还每个常量上面放入了必要的注释！

VVDocumenter-Xcode 使你的生活更加轻松。如果你想定制VVDocumenter-Xcode，在Xcode中，使用 Window>VVDocumenter菜单。

这里，你可以改变自动完成关键字、注释风格以及其他。你想怎样定制 VVDocumenter-Xcode都行。VVDocumenter-Xcode 为我省下了大量的时间！

接下来做什么？

最终完成的示例项目在 这里下载。

在你自己的代码中进行文档化。尝试自己编写 code snippet 并使用VVDocumentor。尝试不同的风格并找出自己的最爱，在实际工作中使用它们。

无疑，对于你来说，苹果 HeaderDoc 用户指南也是一个很好的学习文档。

如果你有任何疑问或建议，请在下面的讨论中告诉我。