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

Question

我需要为我的工作场所实施文档生成解决方案，并将其范围缩小到标题中提到的三个。在这些解决方案之间进行正式比较时，我只能找到很少的信息，我希望你们中在上述一项或多项方面有经验的人可以参与进来：

以下是我从最初的通行证中收集到的信息：

HeaderDoc 优点：与苹果现有的文档一致，与制作苹果文档集的兼容性
HeaderDoc 缺点：难以修改行为，项目没有积极开展，许多人已经放弃了它（这意味着一定有什么不足，虽然我无法量化）。

Doxygen 优点： 广泛使用基础的积极支持社区 b/c，非常可定制，大多数输出​​类型（如乳胶等）
Doxygen 缺点： 需要努力使其看起来/行为与苹果文档一致，与苹果文档集的兼容性并不那么简单

AppleDoc 优点： 看起来与苹果现有的文档一致，兼容制作苹果文档集，
AppleDoc 缺点： 正在积极开发的 typedef、枚举和函数的文档存在问题

这听起来准确吗？我们想要的解决方案将有：

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

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

Answer 1

作为 doxygen 的创建者和主要开发者，我也提供一下我的观点
（显然也有偏见;-)

如果您正在寻找 100% 忠实于 Apple 自己的文档风格的副本，那么 AppleDoc 在这方面是一个更好的选择。使用 doxygen，您将很难获得完全相同的外观，因此我不建议您尝试。

关于 Xcode 文档集； 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。

可以在 here 找到一个在 Objective-C 中使用 doxygen 的真实示例。

doxygen 的开发高度依赖于用户反馈。我们有一个活跃的mailing list 用于提问和讨论，bug tracker 用于错误和功能请求。

大多数 doxygen 用户将它用于 C 和 C++ 代码，因此这些语言自然拥有最成熟的支持，并且输出更针对这些语言的特性和需求进行调整。也就是说，其他语言的愿望和问题也被认真对待。

请注意，我自己在 Mac 上进行几乎所有的 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：您可以在主页中包含自定义文档，不知道是否可以包含更多页面。

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

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

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

我目前正在处理cover most glaring issues 的重大更新，包括对枚举、结构等的支持。一旦我完成更大的块并使其足够稳定，我就会定期将新东西推送到实验分支，所以你可以跟随进度。但现在还很早，进度取决于我的时间，所以可能需要很长时间才能找到有效的解决方案。

Answer 3

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

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