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

Question

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

doxygendocumentation-generationheaderdocappledoc

74

我需要为我的工作场所实现一个文档生成解决方案，并将其缩小到标题中提到的三个选项。我只能从初始阶段得出以下信息：

HeaderDoc 优点：与苹果现有文档保持一致，兼容制作苹果 docsets HeaderDoc 缺点：难以修改行为，项目没有得到积极开发，许多人已经放弃使用它（这意味着其中必须存在某些不足，尽管我不能量化）。

Doxygen 优点：拥有广泛的用户基础，因此具有活跃的支持社区，高度可定制，大部分输出类型（如拉丁字母等） Doxygen 缺点：需要投入工作使其外观/行为与苹果文档保持一致，与苹果 docsets 的兼容性不像 HeaderDoc 一样简单。

AppleDoc 优点：看起来与苹果现有文档保持一致，兼容制作苹果 docsets， AppleDoc 缺点：有关 typedefs、enums 和函数的文档问题，正在积极开发。

我们想要的解决方案将具有：

1. 与苹果 Objective-C 类参考文档一致的外观和感觉。 2. 能够通过选项单击从 Xcode 中调用文档引用，然后链接到文档（就像苹果的类一样）。 3. 智能处理类别、扩展等（包括苹果类别的自定义类别）。 4. 能够创建自己的参考页面（例如本页：Loading…），包括图片，并可以无缝链接到生成的类参考文档，就像苹果的 UIViewController 类参考链接到链接的页面一样。 5. 易于运行命令行命令，可集成到构建脚本中。 6. 优雅地处理非常大的代码库。

基于上述所有信息，有以上哪种解决方案明显优于其他解决方案吗？非常感谢您的任何建议或信息。

- KeithComito

1

FYI，苹果公司的文档《Xcode 5新功能》指出，在“快速帮助面板”和“代码完成弹出视图”中，支持Doxygen和HeaderDoc结构化注释格式。没有提到“AppleDoc”。 - Basil Bourque

3个回答

83

我是appledoc的作者，所以我的回答可能有偏见 :)。尽管如此，我试过所有提到的生成器（还有更多），但感到沮丧的是，没有一个生成器能够产生我想要的结果（和你一样的目标）。

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

统一的外观：appledoc开箱即用，其他需要调整css，但可能可以实现。
生成文档集（用于Xcode引用）：appledoc开箱即支持搜索和选项点击文档，doxygen生成xml和makefile，需要自己调用。此外，appledoc开箱即支持发布的文档集。
类别：appledoc允许您将类别合并到已知类别中或将它们保留为独立的。基础类别和其他苹果类别在索引文件中分别列出。doxygen：当我尝试使用时，它不是最好的选择。
自定义参考页面：appledoc开箱即支持使用markdown或自定义html，doxygen：您可以将自定义文档包含在主页中，不知道是否可以添加更多页面。
简单的命令行：这取决于您的看法：appledoc可以通过命令行开关接受所有参数（还支持可选的全局和项目设置plist文件），因此应该非常容易与构建脚本集成。doxygen需要使用配置文件设置所有参数。

大型代码库：所有工具都应该支持此功能，虽然没有进行时间比较。我不确定是否有任何工具支持缓存值（在以前收集的数据上运行以节省一些时间）-我正在考虑在下一个重大发布版本中添加这个功能。

我已经有一段时间没有尝试使用其他工具了，因此上述关于doxygen/headerdoc的问题可能已经得到解决！ appledoc本身也有缺点：就像你所提到的，它不支持枚举、结构体、函数等（在这方面做了一些工作，请查看这个分支），而且它有自己的一系列问题，这可能会阻止您使用它，取决于您的需求。

我目前正在进行重大更新，将解决大多数突出问题，包括对枚举、结构体等的支持。我会定期将新内容推送到实验分支，只要我完成了较大的块并使其足够稳定，您就可以关注进展情况。但这还很早，进展取决于我的时间，所以可能需要相当长的时间才能实现工作解决方案。

- Tom

Appledoc做得很好！不过，很容易告诉Doxygen安装Xcode docset...另外，Doxygen支持缓存例如类图。 - Jasper Blues

更新：实际上我尝试在Xcode5中安装docset，但它无法工作。一个bug？已经提交了一个。 - Jasper Blues

12

Xcode 5现在会解析你的注释以搜索文档并显示出来：

Comment example

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

- Quxflux

@Jasper 通常需要一些时间让解析器“看到”您的注释（截至Xcode 6.2）。对我来说，构建总是可以解决这个问题。 - joakim

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- doxygen · Accepted Answer

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

如果你在寻找一个 100% 忠实复制苹果官方文档风格的工具，那么 AppleDoc 在这方面是更好的选择。使用 doxygen 你很难得到完全相同的效果，所以我不建议尝试。

关于 Xcode docsets，苹果提供了说明如何在 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和man页面。

Doxygen还超越了纯文档；doxygen可以从源代码创建各种图形和图表（请参见dot相关选项）。Doxygen还可以创建一个可浏览并带有语法突出显示的代码版本，并与文档交叉引用（请参见源浏览器相关选项）。

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

使用Doxygen进行Objective-C的不错的现实生活示例可以在这里找到。

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

大多数doxygen用户使用它来处理C和C++代码，因此针对这些语言的支持最成熟，输出更加符合这些语言的特性和需求。尽管如此，也会认真考虑其他语言的要求和问题。

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