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

Question

我需要为我的工作场所实施文档生成解决方案，并将其缩小到标题中提到的三个。我已经能够找到这些解决方案之间形式化比较的非常少的信息，我希望那些有上述一个或多个经验的人可以权衡：

以下是我从初次传球中收集到的内容：

HeaderDoc优点：与苹果现有的文档一致，与制作苹果文档集的兼容性 HeaderDoc缺点：难以修改行为，项目没有积极处理，许多人已经离开它（意味着必须有一些不足之处，尽管我无法量化它）。

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

AppleDoc专业人士：看起来与苹果现有的文档一致，与制作苹果文档集的兼容性， AppleDoc缺点：正在开发的有关typedef，枚举和函数文档的问题

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

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

根据以上所有信息，上述任何一种解决方案明显优于其他解决方案吗？任何建议或信息，将非常感激。

Answer 1

作为doxygen的创建者和首席开发者，让我也提供我的观点 （显然也有偏见;-)

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

关于Xcode docsets; 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一样。

使用doxygen for Objective-C的一个很好的现实例子可以找到here。

doxygen的发展很大程度上取决于用户的反馈。我们有一个活跃的mailing list用于问题和讨论，还有一个bug tracker用于错误和功能请求。

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

请注意，我自己做了几乎所有的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现在将解析您的注释以搜索文档并显示它：

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