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

我需要为我的工作场所实施一个文档生成解决方案，并将其范围缩小到标题中提到的三个。通过对这些解决方案进行形式化比较的方式，我已经能够找到很少的信息，并且我希望那些具有上述一种或多种经验的人能够参与其中：

这是我从最初的通行证中学到的东西：

HeaderDoc优点：与Apple的现有文档一致，与制作Apple文档集兼容
。HeaderDoc缺点：难以修改行为，项目未积极开展工作，许多人已经放弃了它（这意味着必须存在某些缺陷，尽管我无法对其进行量化） ）。

Doxygen优点：具有广泛使用基础，非常可定制的大多数输出​​类型（如乳胶等）的主动支持社区b / c
Doxygen缺点：需要努力使其外观与Apple Docs一致，与Apple docsets的兼容性并不是那么简单

AppleDoc优点：外观与Apple现有文档一致，与制作Apple文档集兼容，
AppleDoc缺点：积极开发typedef，枚举和函数文档的问题

这听起来准确吗？我们所需的解决方案将具有：

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

根据以上所有信息，上述任何解决方案是否明显优于其他解决方案？任何建议或补充信息将不胜感激。

作为doxygen的创造者和主要开发者，让我也提供自己的看法
（显然也有偏见；-）

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

关于Xcode文档集；苹果提供的说明如何设置了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 -（有关示例，请参见FAQ的问题17 ）。

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

Doxygen还超越了纯粹的文档记录；doxygen可以从源代码创建各种图形和图表（请参见与点相关的选项）。Doxygen还可以创建代码的可浏览和语法突出显示的版本，并将其与文档进行交叉引用（请参阅与源浏览器相关的选项）。

对于中小型项目，Doxygen的速度非常快（尽管生成图的速度可能很慢，但是如今并行运行在多个CPU内核上，一次运行的图形可在下一次运行中重用）。对于非常大的项目（例如，数百万行代码），doxygen可以将项目拆分为多个部分，然后可以将这些部分链接在一起，正如我在此说明的。

可以在此处找到将doxygen用于Objective-C的真实示例。

氧气的产生在很大程度上取决于用户的反馈。我们有一个活跃的邮件列表，用于问题和讨论，以及一个错误跟踪器，用于错误和功能请求。

doxygen的大多数用户都将其用于C和C ++代码，因此自然地，这些语言具有最成熟的支持，并且输出针对这些语言的功能和需求进行了调整。话虽如此，其他语言的希望和问题也得到了认真对待。

请注意，我几乎是在Mac上进行所有Doxygen开发和大多数测试的。

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

根据您的观点（我只提到appledoc和doxygen，我不太清楚headerdoc）：

1. 外观一致：Appledoc开箱即用，其他需要调整CSS，但可能可行。

2. 文档集的生成（用于Xcode参考）：appledoc完全支持开箱即用的可搜索文档和选项单击文档，doxygen生成xml和makefile，您需要自己调用它们。此外，appledoc还支持开箱即用的已发布文档集。

3. 类别：appledoc允许您将类别合并到已知的类或将它们分开，基础和其他Apple类类别在索引文件中单独列出。doxygen：我尝试时效果不佳。

4. 自定义参考页面：appledoc支持使用markdown或自定义html，doxygen开箱即用：您可以将自定义文档包含到主页中，不知道是否可以包含更多页面。

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

6. 大型代码库：尽管没有按时间比较，但所有工具都应支持此功能。同样不确定是否有任何工具支持缓存的值（为了节省时间而运行在先前收集的数据上）-我正在考虑在下一个主要版本中添加它。

自从我尝试使用其他工具以来已有一段时间，因此上面提到的doxygen / headerdoc问题可能已经解决！appledoc本身也有缺点：就像您提到的那样，不支持枚举，结构，函数等（朝着这个方向做了一些工作，请检查此fork），并且它有一系列自己的问题可能会阻止您使用它，具体取决于您的要求。

我目前正在进行主要更新，涵盖大多数明显的问题，包括对枚举，结构等的支持。一旦完成较大的块并使其足够稳定，我就会定期将新内容推送到实验分支，因此您可以按照进展。但是现在还很早，进度取决于我的时间，因此可能需要一段时间才能找到解决方案。

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

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