Objective-C 文档生成器: HeaderDoc 对 Doxyvs.AppleDoc

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

以下是我从最初的通行证中得到的信息:

HeaderDoc 优点: 与苹果现有的文档保持一致，与制作苹果文档集兼容
HeaderDoc 的缺点: 难以修改行为，项目没有积极的工作，许多人已经转离它(这意味着一定有什么缺陷，虽然我不能量化它)。

优点: 主动支持广泛使用的社区 b/c，非常可定制，大多数输出类型(如乳胶等)
缺氧缺点: 采取工作，使其外观/行为与苹果文档一致，与苹果文档集的兼容性不是那么简单

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

这听起来准确吗? 我们期望的解决方案将包括:

  • 与苹果目标一致的外观和感觉-c 类引用
  • 可以选择-点击从 Xcode 内部提取文档参考，然后链接到文档(就像苹果的类一样)
  • 智能处理类别、扩展等(甚至是苹果类的自定义类别)
  • 能够创建我们自己的参考页面(像这个页面: 加载... ，可以包括图像，并可以从生成的类引用链接无缝，如苹果的 UIViewController 类引用链接到链接页面。
  • 易于运行可以集成到生成脚本中的命令行命令
  • 非常大的代码库的优雅处理

基于上述所有信息，上述任何解决方案是否明显优于其他解决方案？如有任何建议或信息需要补充，我们将不胜感激。

19981 次浏览
小开

我是 appledoc 的作者，所以这个回答可能有偏见:)我尝试了所有提到的生成器虽然(和更多) ，但失望，因为没有产生结果，我想有(类似的目标)。

根据你的观点(我只提到了 appledoc 和 doxygen，我不太记得 headerdoc) :

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

  2. 生成文档集(用于 Xcode 引用) : appledoc 完全支持可搜索和可选的文档，doxygen 生成 xml 和 makefile，您需要调用它们。此外，appledoc 支持 出版的文件集开箱即用。

  3. 分类: appledoc 允许你对已知类别进行 合并类别或将它们分开，Foundation 和其他苹果类别在 索引文件中分别列出。我试的时候效果不是很好。

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

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

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

我已经有一段时间没有尝试使用其他工具了，所以上面提到的 doxygen/headerdoc 的问题可能已经解决了！Appledoc 本身也有缺点: 就像你提到的不支持枚举、结构、函数等(有一些工作是在这个方向上完成的，看看这个叉子) ，它有自己的 一系列的问题，可能会阻止你使用它，这取决于你的需求。

我目前正在工作的主要更新，将 涵盖最突出的问题，包括支持枚举，结构等。一旦我完成了更大的块，并使其足够稳定，我就会定期将新内容推送到实验分支，这样你就可以跟踪进展。但现在还为时尚早，进展取决于我的时间，所以可能需要相当长的一段时间才能找到解决方案。

小开
最佳答案

作为氧气的创造者和主要开发者，让我也提供我的观点
(显然也有偏见; -)

如果你正在寻找一个100% 忠实复制苹果自己的文档风格，那么 AppleDoc 在这方面是一个更好的选择。有了多克斯，你将很难得到完全相同的外观，所以我不建议尝试。

关于 Xcode 文档集，Apple 提供了 指示如何使用 doxygen (在 Xcode 3发布时编写)来设置它。对于 Xcode 4，还有一个 不错的向导如何整合 doxygen。

在1.8.0版本中，doxygen 支持 降价，以及大量附加的 加价命令。

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

Dox 使用一个配置文件作为输入。可以使用 doxygen -g生成具有默认值的模板，也可以使用 图形化编辑器创建和编辑模板。您还可以通过使用 doxygen -的脚本通过 doxygen 管道输送选项(参见 常见问题的问题17中的示例)

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

Doxy2也不仅仅是纯文档; doxy2可以从源代码创建各种图表和图表(请参阅 点相关选项)。Doxy还可以创建一个可浏览的、语法突出显示的代码版本，并与文档进行交叉引用(参见 源代码浏览器相关选项)。

对于中小型项目来说，Doxy速度非常快(尽管图表的生成速度可能很慢，但是现在并行地运行在多个 CPU 核上，一次运行的图表在下一次运行中被重用)。 对于非常大的项目(例如数百万行代码) ，doxygen 允许项目被分成多个部分，然后可以像我解释的 给你那样将这些部分连接在一起。

我们可以在 给你中找到一个很好的将 doxygen 用于 Objective-C 的实际例子。

强氧的发展在很大程度上取决于用户的反馈。对于问题和讨论，我们有一个活跃的 邮件列表; 对于 bug 和特性请求，我们有一个活跃的 虫子追踪器。

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

请注意，几乎所有的氧气开发和大多数测试都是我自己在 Mac 上完成的。

小开

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

Comment example

您不必再使用 appledoc 或 doxygen (至少在不想导出文档时)。更多信息可以找到 给你


提交答案