74

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

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

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

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

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

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

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

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

4

3 回答 3

90

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

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

关于 Xcode 文档集；Apple 提供了如何使用 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 -的问题 17 以获取示例）

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

Doxygen 也超越了纯粹的文档。doxygen 可以从源代码创建各种图形和图表（参见点相关选项）。Doxygen 还可以创建代码的可浏览和语法高亮版本，并与文档交叉引用（请参阅源浏览器相关选项）。

Doxygen 对于中小型项目非常快（虽然图表生成可能很慢，但现在并行运行在多个 CPU 内核上，并且一次运行的图表在下一次运行中被重用）。对于非常大的项目（例如数百万行代码），doxygen 允许将项目拆分为多个部分，然后可以将这些部分链接在一起，正如我在此处解释的那样。

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

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

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

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

于 2012-04-12T18:41:15.357 回答
83

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

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

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

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

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

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

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

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

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

我目前正在进行重大更新，将涵盖最明显的问题，包括对枚举、结构等的支持。一旦我完成更大的块并使其足够稳定，我就会定期将新东西推送到实验分支，所以你可以关注进步。但现在还很早，进展取决于我的时间，所以可能需要很长时间才能找到解决方案。

于 2012-04-12T12:32:42.737 回答
12

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

评论示例

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

于 2013-09-19T16:05:12.750 回答