Objective-C文档生成器:HeaderDoc与Doxygen vs. AppleDoc

我需要为我的工作场所实施文档生成解决scheme,并缩小到标题中提到的三个解决scheme。 在这些解决scheme之间的forms化比较中,我能够find很less的信息,我希望那些有上述经验的人能够衡量:

这是我从最初的传球中能够收集到的东西:

HeaderDoc优点:与苹果现有的文档一致,与制作苹果docset的兼容性
HeaderDoc缺点:很难修改行为,项目并没有积极的工作,很多人已经离开了它(这意味着一定有什么不足,尽pipe我无法量化)。

Doxygen优点:积极支持社区B / C广泛的使用基地,非常可定制的,多数输出types(如乳胶等)
Doxygen缺点:使其看起来/行为与苹果文档一致,与苹果docsets的兼容性不是那么简单

AppleDoc优点:看起来与苹果现有的文档一致,与制作苹果docsets的兼容性,
AppleDoc缺点:正在积极开发typedefs,枚举和函数的文档

这听起来准确吗? 我们期望的解决scheme将有:

  • 一致的外观和感觉与苹果objective-c类参考
  • 能够select单击从Xcode中提取文档参考,然后链接到文档(就像苹果的类)
  • 智能处理类别,扩展名等(甚至是苹果类的自定义类别)
  • 能够创build我们自己的参考页面(就像这个页面:加载…可以包括图像,并可以从生成的类引用无缝链接,如苹果的UIViewController类引用链接到链接的页面。
  • 易于运行可集成到构build脚本中的命令行命令
  • 优美的处理非常大的代码库

基于以上所有的信息,上面的解决scheme是否明显比其他解决scheme好? 任何build议或信息添加将非常感激。

作为doxygen的创造者和首席开发者,让我也提供我的观点
(显然有偏见;-)

如果您正在寻找100%忠实的苹果自己的文档样式的副本,那么AppleDoc在这方面是一个更好的select。 随着doxygen你会很难得到完全相同的外观,所以我不会build议尝试。

关于Xcode docsets; Apple提供了如何使用doxygen(在Xcode 3发布的时候编写)进行设置的说明。 对于Xcode 4,如何整合doxygen也是一个不错的指南 。

从版本1.8.0开始,doxygen支持Markdown标记以及大量附加标记命令。

使用doxygen,您可以在主页(@mainpage)和子页面上使用文档(使用@subpage或@page)。 在页面内部,您可以创build部分和子部分。 事实上,doxygen的用户手册完全是用doxygen编写的。 除此之外,您可以将类或函数组合在一起(使用@defgroup和@ingroup),并在类内部自定义部分(使用@name)。

Doxygen使用一个configuration文件作为input。 您可以使用doxygen -g生成具有默认值的模板,或者使用graphics编辑器来创build和编辑模板。 你也可以通过使用doxygen -的脚本通过doxygenpipe道选项doxygen - (参见常见问题的问题17作为例子)

Doxygen不限于Objective-C,它支持包括C,C ++和Java在内的大量语言。 Doxygen也不仅限于Mac平台,例如它也可以在Windows和Linux上运行。 Doxygen的输出也支持更多的不仅仅是HTML; 您可以生成PDF输出(通过LaTeX)或RTF和手册页。

Doxygen也超越了纯文档; doxygen可以从源代码创build各种graphics和图表(请参阅点相关选项)。 Doxygen还可以创build代码的可浏览和语法高亮版本,并与文档(请参阅源浏览器相关选项)进行交叉引用。

Doxygen对于中小型项目来说是非常快的(图表生成速度可能会很慢,但是现在可以在多个CPU内核上并行运行,并且下一次运行的graphics可以重复使用)。 对于非常大的项目(例如数百万行代码),doxygen允许将项目拆分成多个部分,然后按照我在这里所解释的将各个部分连接起来。

在Objective-C中使用doxygen的一个很好的现实例子可以在这里find。

doxygen的发展高度依赖于用户的反馈。 我们有一个活跃的问题和讨论邮件列表和一个错误跟踪器的错误和function请求。

doxygen的大多数用户使用它的C和C + +代码,所以自然这些语言有最成熟的支持和输出更加调整这些语言的function和需求。 也就是说,也希望和其他语言的问题得到重视。

请注意,我几乎所有的doxygen开发和大多数testing都是在Mac上进行的。

我是appledoc的作者,所以这个答案可能是有偏见的:)虽然我尝试了所有提到的生成器(但更多),但因为没有产生我想要的结果而感到沮丧(与你类似的目标)。

根据你的观点(我只提到appledoc和doxygen,我不记得headerdoc那么好):

  1. 一致的外观:开箱即用的appledoc,其他需要调整CSS,但可能是可行的。

  2. 生成文档集(对于Xcode引用):appledoc完全支持可search和可选的可点击文档,doxygen生成xml和makefile,您需要自行调用。 另外,appledoc支持发布docbox 。

  3. 类别:appledoc允许您将类别合并到已知的类中或将它们分开,基础和其他Apple类别在索引文件中分别列出。 doxygen:当我尝试它时,这不是最好的。

  4. 自定义参考页面:appledoc 支持使用markdown或自定义html,doxygen:您可以包含自定义文档到主页面,不知道是否可以包含更多的页面。

  5. 简单的命令行:取决于你如何看待它:appledoc可以通过命令行开关(但也支持可选的全局和项目设置plist文件)的所有参数,所以它应该是非常容易与生成脚本集成。 doxygen需要使用configuration文件来设置所有参数。

  6. 大的代码库:所有的工具都应该支持这个,虽然没有比较时间。 也不知道是否有任何工具支持caching值(运行在以前收集的数据,以节省一些时间) – 我正在寻找添加此为下一个主要版本。

从我尝试使用其他工具开始,有一段时间,所以上面提到的doxygen / headerdoc问题可能已经被解决了! appledoc本身也有缺点:像你提到的那样,不支持枚举,结构体,函数等(这方面做了一些工作, 检查这个分支 ),它有自己的一系列问题 ,可能会阻止你使用它你的要求。

我目前正在进行重大的更新,将涵盖最显眼的问题 ,包括支持枚举,结构等。我会定期向试验分支推出新的东西,只要我完成更大的块,使其足够稳定,所以你可以按照进展。 但还是很早,进度取决于我的时间,所以可能需要一段时间,直到工作的解决scheme。

Xcode 5现在将parsing您的注释以search文档并显示它:

评论的例子

您不必再使用appledoc或doxygen(至less当您不想导出文档时)。 更多信息可以在这里find