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

我需要为我的工作场所实施文档生成解决scheme，并缩小到标题中提到的三个解决scheme。 在这些解决scheme之间的forms化比较中，我能够find很less的信息，我希望那些有上述经验的人能够衡量：

这是我从最初的传球中能够收集到的东西：

HeaderDoc优点：与苹果现有的文档一致，与制作苹果docset的兼容性
HeaderDoc缺点：很难修改行为，项目并没有积极的工作，很多人已经离开了它（这意味着一定有什么不足，尽pipe我无法量化）。

Doxygen优点：积极支持社区B / C广泛的使用基地，非常可定制的，多数输出types（如乳胶等）
Doxygen缺点：使其看起来/行为与苹果文档一致，与苹果docsets的兼容性不是那么简单

AppleDoc优点：看起来与苹果现有的文档一致，与制作苹果docsets的兼容性，
AppleDoc缺点：正在积极开发typedefs，枚举和函数的文档

这听起来准确吗？ 我们期望的解决scheme将有：

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

基于以上所有的信息，上面的解决scheme是否明显比其他解决scheme好？ 任何build议或信息添加将非常感激。

Answer 1

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

如果您正在寻找100％忠实的苹果自己的文档样式的副本，那么AppleDoc在这方面是一个更好的select。 随着doxygen你会很难得到完全相同的外观，所以我不会build议尝试。

关于Xcode docsets; Apple提供了如何使用doxygen（在Xcode 3发布的时候编写）进行设置的说明。 对于Xcode 4，如何整合doxygen也是一个不错的指南 。

从版本1.8.0开始，doxygen支持Markdown标记以及大量附加标记命令。

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

Doxygen使用一个configuration文件作为input。 您可以使用doxygen -g生成具有默认值的模板，或者使用graphics编辑器来创build和编辑模板。 你也可以通过使用doxygen -的脚本通过doxygenpipe道选项doxygen - （参见常见问题的问题17作为例子）

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

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

Doxygen对于中小型项目来说是非常快的（图表生成速度可能会很慢，但是现在可以在多个CPU内核上并行运行，并且下一次运行的graphics可以重复使用）。 对于非常大的项目（例如数百万行代码），doxygen允许将项目拆分成多个部分，然后按照我在这里所解释的将各个部分连接起来。

在Objective-C中使用doxygen的一个很好的现实例子可以在这里find。

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

doxygen的大多数用户使用它的C和C + +代码，所以自然这些语言有最成熟的支持和输出更加调整这些语言的function和需求。 也就是说，也希望和其他语言的问题得到重视。

请注意，我几乎所有的doxygen开发和大多数testing都是在Mac上进行的。

Answer 2

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

根据你的观点（我只提到appledoc和doxygen，我不记得headerdoc那么好）：

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

2. 生成文档集（对于Xcode引用）：appledoc完全支持可search和可选的可点击文档，doxygen生成xml和makefile，您需要自行调用。 另外，appledoc支持发布docbox 。

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

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

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

6. 大的代码库：所有的工具都应该支持这个，虽然没有比较时间。 也不知道是否有任何工具支持caching值（运行在以前收集的数据，以节省一些时间） – 我正在寻找添加此为下一个主要版本。

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

我目前正在进行重大的更新，将涵盖最显眼的问题 ，包括支持枚举，结构等。我会定期向试验分支推出新的东西，只要我完成更大的块，使其足够稳定，所以你可以按照进展。 但还是很早，进度取决于我的时间，所以可能需要一段时间，直到工作的解决scheme。

Answer 3

Xcode 5现在将parsing您的注释以search文档并显示它：

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