Xcode HeaderDoc 教程

Posted 2020-09-26 slgkaifa

打开 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 server上。然后全部人都能够訪问你的文档！

VVDocumenter-Xcode

 

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

首先，从 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菜单。

这里，你能够改变自己主动完毕keyword、凝视风格以及其它。你想怎样定制 VVDocumenter-Xcode都行。

VVDocumenter-Xcode 为我省下了大量的时间。

接下来做什么？

终于完毕的演示样例项目在 这里下载。

在你自己的代码中进行文档化。

尝试自己编写 code snippet 并使用VVDocumentor。

尝试不同的风格并找出自己的最爱，在实际工作中使用它们。

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

假设你有不论什么疑问或建议，请在以下的讨论中告诉我。