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

Question

我需要为我的工作场所实施文档生成解决方案，并将其缩小到标题中提到的三个。我已经能够找到这些解决方案之间形式化比较的非常少的信息，我希望那些在上述一个或多个方面有经验的人可以权衡：

以下是我从初次传球中收集到的内容：

HeaderDoc优点：与苹果现有的文档一致，与制作苹果docsets的兼容性 HeaderDoc缺点：难以修改行为，项目没有积极处理，许多人已经离开它（意味着必须有一些不足之处，尽管我无法量化它）。

Doxygen Pros： 积极支持社区b / c广泛使用基础，非常可定制，大多数输出​​类型（如乳胶等）
缺氧缺点： 需要努力使其外观/行为与apple docs一致，与apple docsets的兼容性并不那么简单

AppleDoc专业人士： 看起来与苹果现有的文档一致，与制作苹果文档集的兼容性，
AppleDoc缺点： 有关正在开发的typedef，枚举和函数文档的问题

这听起来准确吗？我们理想的解决方案将包括：

• 苹果Objective-c类参考的一致外观和感觉
• 能够选项 - 单击以从Xcode中提取文档引用，然后链接到doc（就像苹果的类）
• 智能处理类别，扩展等（甚至是苹果课程的自定义类别）
• 能够创建我们自己的参考页面（如此页面：正在加载...可以包含图像，并且可以无缝地链接生成的类引用，例如apple的UIViewController类引用如何链接到链接页面。
• 易于运行的命令行命令，可以集成到构建脚本中
• 优雅处理非常大的代码库

根据以上所有信息，上述任何一种解决方案是否明显优于其他解决方案？任何建议或信息都将非常感激。

Answer 1

作为doxygen的创建者和首席开发者，让我也提供我的观点 （显然也有偏见; - ）

如果您正在寻找100％忠实复制Apple自己的文档样式，那么AppleDoc在这方面是更好的选择。使用doxygen，您将很难获得完全相同的外观，因此我不建议尝试。

关于Xcode docsets; Apple提供instructions如何使用doxygen（在Xcode 3发布时编写）来设置它。对于Xcode 4，还有nice guide如何整合doxygen。

从版本1.8.0开始，doxygen支持Markdown markup，以及大量额外的markup命令。

使用doxygen，您可以在主页面（@mainpage）以及子页面（使用@subpage或@page）中包含文档。在页面内，您可以创建部分和子部分。实际上，doxygen的用户手册完全是用doxygen编写的。除此之外，您可以将类或函数组合在一起（使用@defgroup和@ingroup），并在类中创建自定义部分（使用@name）。

Doxygen使用配置文件作为输入。您可以使用doxygen -g生成包含默认值的模板，也可以使用graphical editor创建和编辑一个模板。您还可以使用doxygen -通过脚本通过doxygen管道选项（例如，请参阅FAQ的问题17）

Doxygen不仅限于Objective-C，它支持多种语言，包括C，C ++和Java。 Doxygen也不限于Mac平台，例如它也可以在Windows和Linux上运行。 Doxygen的输出还支持HTML以外的功能;您可以生成PDF输出（通过LaTeX）或RTF和手册页。

Doxygen也超越了纯文档; doxygen可以从源代码创建各种图形和图表（参见dot相关选项）。 Doxygen还可以创建代码的可浏览和语法突出显示版本，并与文档交叉引用（请参阅source browser相关选项）。

对于中小型项目来说，Doxygen非常快（虽然图表生成速度很慢，但现在并行运行多个CPU核心，一次运行的图形会在下一次运行中重复使用）。 对于非常大的项目（例如数百万行代码），doxygen允许将项目拆分为多个部分，然后可以按照我的解释here将这些部分链接在一起。

可以找到为Objective-C使用doxygen的一个很好的现实例子here。

doxygen的发展很大程度上取决于用户的反馈。我们有问题和讨论的有效mailing list以及错误和功能请求bug tracker。

doxygen的大多数用户都将它用于C和C ++代码，因此这些语言自然拥有最成熟的支持，并且输出更适合这些语言的功能和需求。也就是说，也希望和其他语言的问题得到认真对待。

请注意，我自己做了几乎所有的doxygen开发和大多数测试。

Answer 2

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

根据你的观点（我只提到appledoc和doxygen，我不会很好地回忆起headerdoc）：

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

2. 生成文档集（用于Xcode引用）：appledoc完全支持可搜索和可选择点击的文档，doxygen生成需要自己调用的xml和makefile。此外，appledoc支持published docsets开箱即用。

3. 类别：appledoc允许您merge categories使用已知类或将它们分开，基础和其他苹果类别在index file中单独列出。 doxygen：当我尝试它时效果不佳。

4. 自定义参考页面：appledoc supports开箱即用，使用markdown或自定义html，doxygen：您可以在主页面中包含自定义文档，不知道是否可以包含更多页面。< / p>

5. 简单的命令行：取决于你如何看待它：appledoc可以通过命令行开关获取所有参数（但也支持可选的全局和项目设置plist文件），因此它应该很容易与构建脚本集成。 doxygen需要使用配置文件来设置所有参数。

6. 大型代码库：所有工具都应该支持这一点，尽管没有时间比较。还不确定是否有任何工具支持缓存值（运行先前收集的数据以节省一些时间） - 我正在考虑将其添加到下一个主要版本中。

我尝试使用其他工具已经有一段时间了，所以上面提到的doxygen / headerdoc问题可能已经解决了！ appledoc本身也有缺点：就像你提到的那样，没有对枚举，结构，函数等的支持（在这方面做了一些工作，check this fork），它有自己的set of issues可能会阻止你根据您的要求使用它。

我目前正致力于cover most glaring issues的主要更新，包括对枚举，结构等的支持。我一旦完成更大的块并使其足够稳定，我会定期将新内容推送到实验分支，所以你可以跟进进度。但它仍然很早，进度取决于我的时间，因此可能需要一段时间才能找到解决方案。

Answer 3

Xcode 5现在将解析您的评论以搜索文档并显示它：

您不必再使用appledoc或doxygen（至少在您不想导出文档时）。可以找到更多信息here