Objective-C文档生成器:HeaderDoc vs. Doxygen vs. AppleDoc
Kei*_*ito 74 doxygen documentation-generation headerdoc appledoc
我需要为我的工作场所实施文档生成解决方案,并将其缩小到标题中提到的三个.我已经能够在这些解决方案之间进行正式比较的方式中找到很少的信息,我希望那些在上述一个或多个方面有经验的人可以权衡:
以下是我从初次传球中收集到的内容:
HeaderDoc优点:与苹果公司现有的文档一致,与制作苹果文档集的兼容性
HeaderDoc缺点:难以修改行为,项目没有积极处理,许多人已经转离它(意味着必须有一些不足之处,尽管我无法量化它).
Doxygen Pros:活跃支持社区b/c广泛使用基础,非常可定制,大多数输出类型(如乳胶等)
Doxygen缺点:工作使其外观/行为与apple docs一致,与apple docsets的兼容性并不那么简单
AppleDoc专业人士:看起来与苹果现有的文档一致,与制作苹果文档集的兼容性,
AppleDoc缺点:有关typedef,枚举和函数文档的问题,正在积极开发中
这听起来准确吗？我们理想的解决方案将:
- 苹果Objective-c类参考的一致外观
- 能够选项单击以从Xcode中提取文档引用,然后链接到doc(就像苹果的类)
- 智能处理类别,扩展等(甚至是苹果类的自定义类别)
- 能够创建我们自己的参考页面(比如这个页面:Loading ...可以包含图像,并且可以无缝地链接生成的类引用,就像apple的UIViewController类引用链接到链接页面一样.
- 易于运行的命令行命令,可以集成到构建脚本中
- 优雅地处理非常大的代码库
根据以上所有信息,上述任何一种解决方案明显优于其他解决方案吗？任何建议或信息,将非常感激.
dox*_*gen 89
作为doxygen的创建者和首席开发者,让我也提供我的观点
(显然也有偏见;-)
如果您正在寻找Apple自己的文档风格的100%忠实复制品,那么AppleDoc在这方面是更好的选择.使用doxygen,你将很难获得完全相同的外观,所以我不建议尝试.
关于Xcode docsets; 苹果提供的说明如何设置了doxygen的(写在时间的Xcode 3被释放).对于Xcode 4,还有一个很好的指南如何集成doxygen.
从版本1.8.0开始,doxygen支持Markdown标记,以及大量额外的标记命令.
使用doxygen,您可以在主页面(@mainpage)以及子页面(使用@subpage或@page)中包含文档.在页面内,您可以创建部分和子部分.实际上,doxygen的用户手册完全是用doxygen编写的.除此之外,您可以将类或函数组合在一起(使用@defgroup和@ingroup)并在类中创建自定义部分(使用@name).
Doxygen使用配置文件作为输入.您可以使用默认值生成模板,也可以doxygen -g使用图形编辑器创建和编辑模板.您还可以通过脚本使用doxygen来管道选项doxygen -(参见常见问题解答的问题17 )
Doxygen不仅限于Objective-C,它支持多种语言,包括C,C++和Java.Doxygen也不仅限于Mac平台,例如它也可以在Windows和Linux上运行.Doxygen的输出还支持HTML以外的功能; 您可以生成PDF输出(通过LaTeX)或RTF和手册页.
Doxygen也超越了纯文档; doxygen可以从源代码创建各种图形和图表(参见点相关选项).Doxygen还可以创建代码的可浏览和语法突出显示版本,并与文档交叉引用(请参阅源浏览器相关选项).
对于中小型项目,Doxygen非常快(虽然图表生成速度很慢,但现在并行运行多个CPU核心,一次运行的图形在下一次运行中重复使用).对于非常大的项目(例如数百万行代码),doxygen允许项目分成多个部分,然后可以将这些部分链接在一起,如我在此处所解释的那样.
在这里可以找到使用doxygen for Objective-C的一个很好的现实例子.
doxygen的发展很大程度上取决于用户的反馈.我们有一个用于问题和讨论的活动邮件列表以及针对错误和功能请求的错误跟踪器.
doxygen的大多数用户都将它用于C和C++代码,因此这些语言自然而然地拥有最成熟的支持,并且输出更适合这些语言的功能和需求.也就是说,也希望和其他语言的问题得到认真对待.
请注意,我自己做几乎所有的doxygen开发和大多数测试.
Tom*_*Tom 82
我是appledoc的作者,所以这个答案可能有偏见:)虽然我尝试了所有提到的生成器(以及更多),但由于没有产生我想要的结果(与你类似的目标)而感到沮丧.
根据你的观点(我只提到appledoc和doxygen,我不会很好地回忆起headerdoc):
一致的外观:appledoc开箱即用,其他需要调整css,但可能是可行的.
生成文档集(用于Xcode引用):appledoc完全支持可搜索和可选择的可点击文档,doxygen生成需要自己调用的xml和makefile.此外,appledoc支持开箱即用的已发布文档集.
类别:appledoc允许您将类别合并到已知类或将它们分开,基础和其他苹果类类别在索引文件中单独列出.doxygen:当我尝试它时,这不是最好的.
自定义参考页面:appledoc 支持使用markdown或自定义html开箱即用,doxygen:您可以在主页面中包含自定义文档,不知道是否可以包含更多页面.
简单的命令行:取决于你如何看待它:appledoc可以通过命令行开关获取所有参数(但也支持可选的全局和项目设置plist文件),因此它应该很容易与构建脚本集成.doxygen需要使用配置文件来设置所有参数.
大型代码库:所有工具都应该支持这一点,尽管没有时间比较.还不确定是否有任何工具支持缓存值(运行先前收集的数据以节省一些时间) - 我正在考虑为下一个主要版本添加此项.
我尝试使用其他工具已经有一段时间了,所以上面提到的doxygen/headerdoc问题可能已经解决了!appledoc本身也有缺点:就像你提到的那样,没有对枚举,结构,函数等的支持(在这个方向上做了一些工作,检查这个分支),它有它自己的一组问题,可能会阻止你使用它,取决于你的要求.
我目前正在进行重大更新,将涵盖最明显的问题,包括对枚举,结构等的支持.一旦我完成更大的块并使其足够稳定,我会定期将新内容推送到实验分支,因此您可以按照进展.但现在还很早,进度取决于我的时间,因此可能需要一段时间才能找到解决方案.
