HeaderDoc注释及文档生成

普通注释

通常情况下,在OC中写一条注释的最简单的方法是用两条斜杠, 但是如果想生成注释问文档就需要用结构化的方法使用标签符号来标记,以便可以在不同的地方显示. 比如:


1. 在Utilities面板的Quick Help Inspector里.
2. 当你按下Option键然后点击方法,类或属性名时弹出的帮助菜单 Help Popup里.
3. 在代码实现弹出框里.



良好的代码注释可以使用更多的工具来为你的应用创建完整的HTML文档, 比如HeaderDoc, 通常的注释区域可以有以下三种方法


1. /* — /
2. /! — /
3. ///

文档化注释

这是主要使用第二种方法,因为他可以完全被HeaderDoc文档识别,下面是使用注释常用的一些标签

  • @brief: 使用它来写一段你正在文档化的method, property, class, file, struct, 或enum的短描述信息。

  • @discussion: 用它来写一段详尽的描述。如果需要你可以添加换行。

  • @param: 通过它你可以描述一个 method 或 function的参数信息。你可以使用多个这种标签。

  • @return: 用它来制定一个 method 或 function的返回值。

  • @see: 用它来指明其他相关的 method 或 function。你可以使用多个这种标签。

  • @sa: 同前一条类似。

  • @code: 使用这个标签,你可以在文档当中嵌入代码段。当在Help Inspector当中查看文档时,代码通过在一个特别的盒子中用一种不同的字体来展示。始终记住在写的代码结尾处使用@endcode标签。

  • @remark:在写文档时,用它来强调任何关于代码的特殊之处。

  • 更多的标签可以在官方文档中看到

    具体在Xcode中如图所示.
    chaox

    在Utilities面板打开 Help Inspector,会找到相同的文档。
    chaox

    在键盘上按住Option 键点击属性也会弹出注释.
    chaox

    文件的注释

    下面是文件注释一些常用到的标签

    • @file: 使用这个标签来指出你正在记录一个文件(header 文件或不是)。如果你将使用Doxygen来输出文档,那么你最好在这个标签后面紧接着写上文件名字。它是一个top level 标签。
    • @header 跟上面的类似,但是是在 HeaderDoc中使用。当你不使用 Doxygen时,不要使用上面的标签。
    • @author 用它来写下这个文件的创建者信息
    • @copyrighe 添加版权信息
    • @version 用它来写下这个文件的当前版本

    简单用法

    文件头
    chaox


    点击文件名


    cc

    类目,代理都可以这样来添加注释

    这些注释如果手动添加是非常麻烦的, 好在有喵大解决了这个问题, github上有喵大的一个xcode插件 VVDocumenter

    解决错误


    Xcode 能帮你检查工作,就像Xcode会自动检查代码中的语法错误?有一个好消息,Clang 有一个标志,叫做“CLANG_WARN_DOCUMENTATION_COMMENTS”,可以用于检查 HeaderDoc 格式的注释。


    打开 DocumentationExamples的项目设置,点击 Build Settings,找到 DocumentationComments, 将值设置为 YES。 打开 MathAPI.h,将第一个 @param 标签的参数名由firstNumber 修改为thirdNumber,然后编译。 有一个警告发生,甚至提出了修改建议。它不会影响任何事情,但有助于检查文档中的错误。


    12.png


    特殊注释

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

    // 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个注释以粗体显示:

    举个栗子
    aa

    cca

    用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打开正常。
  • 最新版本的headerdoc2html 不能正确解析 /// 类的注释,可以使用 /*! 类型的注释代替。
  • 这很酷,但还可以更进一步。除了手动进入到输出目录中进行导航,HeaderDoc还会创建一个主目录索引。 返回终端,导航至新建的 documentation 目录,输入:

    cd ~/Desktop/documentation

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

    gatherheaderdoc .

    gatherheaderdoc自动查找目录,为 . 目录(表示当前目录)创建索引。 用 Finder 打开 documentation 目录。你会发现多出一个 masterTOC.html 文件。打开它,它将列出所有已文档化的属性、方法、枚举和块的链接。 你可以将所有 HTML 文件放到 web 服务器上,然后所有人都可以访问你的文档。