标签：des style http color 使用 io strong 文件
打开 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中注释：
这些注释不但有助于你浏览代码，而且 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:
问题: 最新版本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 用户指南也是一个很好的学习文档。
如果你有任何疑问或建议，请在下面的讨论中告诉我。
Xcode HeaderDoc 教程（3）,布布扣,bubuko.com
标签：des style http color 使用 io strong 文件
原文地址：http://blog.csdn.net/kmyhy/article/details/38388253
