Objective-C文档生成器：HeaderDoc与Doxygen与AppleDoc [英] Objective-C Documentation Generators: HeaderDoc vs. Doxygen vs. AppleDoc

问题描述

我需要为我的工作场所实施一个文档生成解决方案，并将其范围缩小到标题中提到的三个。在这些解决方案之间进行形式化比较的方式中，我几乎找不到信息，我希望那些具有上述一种或多种经验的人可以称职：

I need to implement a documentation generation solution for my workplace and have narrowed it down to the three mentioned in the title. I have been able to find very little information in the way of formalized comparisons between these solutions, and I'm hoping that those of you with experience in one or more of the above can weigh in:

这是我从最初的通行证中收集到的内容：

Here is what I have been able to glean from my initial pass:

HeaderDoc优点：与Apple现有文档一致，与制作Apple文档集兼容< br>
HeaderDoc缺点：难以修改行为，项目未积极开展工作，许多人放弃了它（这意味着必须存在某些缺陷，尽管我无法量化）。

HeaderDoc Pros: Consistent with apple's existing docs, compatibility with making apple docsets
HeaderDoc Cons: Difficult to modify behavior, project is not actively worked on, many have switched away from it (meaning there must be something deficient, though I can't quantify it).

Doxygen优点：$ b​​ $ b积极支持的社区b / c，用途广泛，非常可定制，大多数输出​​类型（如乳胶等）

Doxygen缺点：
需要努力使其外观/行为与Apple文档一致，与苹果文档集的兼容性并不是那么简单

Doxygen Pros: Active support community b/c of wide use base, very customizable, most output types (like latex etc)
Doxygen Cons: Takes work to make it look/behave consistent with apples docs, compatibility with apple docsets is not as simple

AppleDoc专业人士：
看起来与苹果现有文档一致文档，与制作Apple文档集兼容，

AppleDoc缺点：$ b​​ $ b关于typedef，枚举和函数的文档，正在积极开发中

AppleDoc Pros: Looks consistent with apple's existing docs, compatibility with making apple docsets,
AppleDoc Cons: Issue with documentation of typedefs, enums, and functions, actively being developed

听起来正确吗？我们期望的解决方案将是：

Does this sound accurate? Our desired solution will have:

• 与苹果Objective-C类引用保持一致的外观


• 可以单击选项，从Xcode中提取文档参考，然后链接到文档（就像苹果的类一样）


• 智能处理类别，扩展名等（甚至自定义）苹果类的类别）


• 能够创建我们自己的参考页（例如此页面：正在加载……可以包含图像，并且可以无缝地与生成的类引用链接，例如苹果的UIViewController类参考链接到链接的页面。


• 易于运行可集成到构建脚本中的命令行命令


• 非常大的代码库的优美处理方式

• Consistent look and feel with apples objective-c class reference
• Ability for option-click to pull up documentation reference from within Xcode, and then link to the doc (just like apple's classes)
• Smart handling of categories, extensions, and the like (even custom categories of apple's classes)
• Ability to create our own reference pages (like this page: Loading… that can include images, and be linkable from generated class references seamlessly, like how apple's UIViewController class reference links to the linked page.
• Easy to run command line commands that can be integrated into build scripts
• Graceful handling of very large codebase

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

Based on all of the information above, are any of the above solutions clearly better than the others? Any suggestions or information to add would be extremely appreciated.

解决方案

作为doxygen的创建者和首席开发者，让我也提供我的看法

（显然也有偏见；-）

As the creator and lead developer of doxygen, let me also provide my perspective
(obviously biased as well ;-)

如果您要100％忠实地复制Apple自己的文档样式，则AppleDoc在这方面是一个更好的选择。有了doxygen，您将很难获得完全相同的外观，因此我不建议尝试。

If you are looking for a 100% faithful replica of Apple's own documentation style, then AppleDoc is a better choice in that respect. With doxygen you'll have a hard time to get that exact same look, so I would not recommend to try.

关于Xcode文档集； Apple提供了说明如何使用doxygen进行设置（ Xcode 3发布时编写）。对于Xcode 4，还有一个很好的指南如何集成doxygen。

With respect to Xcode docsets; Apple provides instructions how to set that up with doxygen (written in the time Xcode 3 was released). For Xcode 4 there is also a nice guide how to integrate doxygen.

从1.8.0版开始，doxygen支持降价标记，以及大量其他标记命令。

As of version 1.8.0, doxygen supports Markdown markup, as well a large number of additional markup commands.

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

With doxygen you can include documentation on the main page (@mainpage) as well as on subpages (using @subpage or @page). Inside a page you can create sections and subsections. In fact, doxygen's user manual was completely written using doxygen. Besides that, you can group classes or functions together (using @defgroup and @ingroup) and inside a class make custom sections (using @name).

Doxygen使用配置文件作为输入。您可以使用 doxygen -g 生成具有默认值的模板，也可以使用图形编辑器来创建和编辑一个。您也可以使用 doxygen-通过脚本通过doxygen传递选项（请参阅常见问题解答（例如）

Doxygen uses a configuration file as input. You can generate a template with default values using doxygen -g or use a graphical editor to create and edit one. You can also pipe options through doxygen via a script using doxygen - (see question 17 of the FAQ for an example)

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

Doxygen is not limited to Objective-C, it supports a large range of languages including C, C++, and Java. Doxygen is also not limited to the Mac platform, e.g. it runs on Windows and Linux too. Doxygen's output also supports more than just HTML; you can generate PDF output (via LaTeX) or RTF and man pages.

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

Doxygen also goes beyond pure documentation; doxygen can create various graphs and diagrams from the source code (see the dot related options). Doxygen can also create a browsable and syntax highlighted version of your code, and cross-reference that with the documentation (see the source browser related options).

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

Doxygen is very fast for small to medium sized projects (the diagram generation can be slow though, but nowadays runs on multiple CPU cores in parallel and graphs from one run are reused in the next run). For very large projects (e.g. millions of lines of code) doxygen allows the projects to be split into multiple parts and can then link the parts together as I explained here.

可以找到一个将doxygen用于Objective-C的真实示例。 = http://dl.dropbox.com/u/2601212/NanoStore%202.0/html/index.html rel = nofollow noreferrer>此处。

A nice real-life example of using doxygen for Objective-C can be found here.

氧气的产生在很大程度上取决于用户的反馈。我们有一个有效的邮件列表用于问题和讨论，还有一个错误跟踪器，用于错误和功能请求。

The development of doxygen highly depends on user feedback. We have an active mailing list for questions and discussions and a bug tracker for both bugs and feature requests.

大多数doxygen的用户将其用于C和C ++代码，因此自然而然地，这些语言获得了最成熟的支持，并且输出针对这些语言的功能和需求进行了调整。话虽如此，其他语言的希望和问题也得到了认真对待。

Most users of doxygen use it for C and C++ code, so naturally these languages have the most mature support and the output is more tuned towards the features and needs for these languages. That said, also wishes for and issues with other languages are taken seriously.

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

Note that I do nearly all doxygen development and most testing on a Mac myself.

这篇关于Objective-C文档生成器：HeaderDoc与Doxygen与AppleDoc的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！