Objective-C文档生成

很多开发者忽略了文档的重要性。

再次打开自己半年前开发的某个项目,会发现思路几乎已忘得一干二净--当时自己做了什么?如何做的?为什么这么做?如果需要增添功能,没有文档的帮助,将会变得十分困难;零星的注释只能帮助代码片段的理解。因为项目已经生疏,需要将整个项目的代码从头到尾、一行一行重新吃透,唤醒大脑中该项目的记忆,才知道如何下手。如果有编写得当的文档,通过查阅文档能很快重新理解项目,也能很快找出与新增功能相关的部分。这将大大提高效率,同时节省了时间。

如果开发者参与团队开发,没有文档就是一场灾难了。当你向团队提交代码后,不得不向其他成员解释你写了什么?为什么这么写?当项目非常庞大时,开发者不可能完全理解其他成员的代码。以上这些都会对时间造成不必要的浪费。在团队开发中编写文档就像某种形式的沟通,同时能帮助其他成员理解自己的代码,毕竟每个人的代码风格都不同。让团队成员理解自己的代码是必不可少的任务。

3个主流的文档生成工具

HeaderDoc

Doxygen

appledoc

注意

  1. 常见的tag有:@brief, @param, @return 完整列表
  2. @character是所有tag的前缀。
  3. 以上符号“@”可以替换为反斜线“\”(@brief变为\brief)。
  4. “\”一般用于Doxygen。
  5. “@”一般用于HeaderDoc。
  6. 使用“@”可以同时适用Doxygen和HeaderDoc。
  7. HeaderDoc只能识别/*! */格式的注释,而Doxygen能识别/*! */和/** */两种格式。
  8. 对于方法(method),生成HTML文档时只会识别头部文件中的注释,其他地方的注释只会在Xcode help显示,并不会加入到生成的HTML文档中。
  9. @field用于描述struct和霉女(Enum)中的单个变量,HeaderDoc能识别,而Doxygen不能。在struct中每个变量顶部用/*! */格式注释,两个工具都能识别。
  10. Xcode支持对@param标签中的参数名进行检查,可在Build Settings中开启。

参考

以下是三个工具的介绍和使用教程:

Documenting Your Objective-C and Swift Code in Xcode with HeaderDoc and Doxygen

使用Objective-C的文档生成工具:appledoc

用 appledoc 生成文档

    原文作者:r_lin
    原文地址: https://www.jianshu.com/p/9f676ce59c89
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞