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

Question

我需要为我的工作场所实现一个文档生成解决方案，并将其范围缩小到标题中提到的三个。我在这些解决方案之间的形式化比较方面找到的信息非常少，我希望那些在上述一项或多项方面有经验的人能够参与进来:

以下是我从最初的过程中收集到的信息:

HeaderDoc 优点:与苹果现有文档一致，兼容制作苹果文档集
HeaderDoc 缺点:很难修改行为，项目没有积极开展，许多人已经放弃了它(这意味着肯定有一些缺陷，尽管我无法量化它)。

Doxygen 优点:积极支持社区b/c，具有广泛的使用基础，非常可定制，大多数输出​​类型(如 latex 等)
多氧缺点:需要努力使其外观/行为与苹果文档一致，与苹果文档集的兼容性并不那么简单

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

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

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

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

Answer 1

作为 doxygen 的创建者和首席开发人员，我也发表一下我的观点
(显然也有偏见；-)

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

关于 Xcode 文档集；苹果提供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 找到使用 doxygen 进行 Objective-C 的一个很好的现实示例。 .

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

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

请注意，几乎所有 doxygen 开发和大部分测试都是我自己在 Mac 上完成的。