Objective-C Documentation Generators: HeaderDoc vs. Doxygen vs. Appledoc

Question

I need to implement a solution for creating documentation for my workplace and narrow it down to the three mentioned in the title. I managed to find very little information about formal comparisons of these solutions, and I hope that those of you who have experience with one or more of the above can weigh:

Here is what I managed to get from my initial pass:

HeaderDoc Pros: compatible with existing Apple documents, compatible with the creation of apple docset
HeaderDoc Cons: It is difficult to change the behavior, the project is not actively working, many of them are disconnected (this means that something is missing, although I can not quantify it).

Doxygen Pros: Active b / c support community for a widely used database, highly customizable, most output types (e.g. latex, etc.)
Doxygen Cons: Does the job to make it look / behave according to apple documents; compatibility with apple documents is not so simple.

AppleDoc Pros: Looks consistent with apple existing documents, apple document compatibility,
AppleDoc Cons: Problem with documenting typedefs, enumerations, and features actively being developed

Does this sound right? Our desired solution will be:

• Consistent appearance with apples objective-c class reference
• Ability to click on a link to pull a link to the documentation from Xcode, and then a link to the document (as well as apple classes)
• Clever processing of categories, extensions, etc. (even Apple's custom class categories)
• The ability to create your own link pages (for example, this page: Loading ..., which can include images, and be easily linked to generated classes, for example, as a Java class link UIViewController links to a linked page.
• Easily run command line commands that can be integrated into build scripts
• Elegant handling with a very large code base

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

Answer 1

As the creator and lead developer of doxygen, let me also introduce my perspective (obviously biased, -)

If you're looking for a 100% faithful copy of Apple's proprietary documentation style, then AppleDoc is the best choice in this regard. With doxygen, it will be difficult for you to find the exact same kind, so I would not recommend a try.

Regarding Xcode docsets; Apple provides instructions on how to install this using doxygen (written from the time Xcode 3 was released). There is also a great reference for Xcode 4 on how to integrate doxygen.

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

With doxygen, you can enable documentation on the main page (@mainpage), as well as on subpages (using @subpage or @page). Inside the page, you can create sections and subsections. In fact, the doxygen user guide has been completely written using doxygen. In addition, you can group classes or functions together (using @defgroup and @ingroup), and create custom sections within a class (using @name).

Doxygen uses the configuration file as input. You can create a template with default values ​​using doxygen -g or use the graphical editor to create and edit it. You can also pass parameters via doxygen through a script using doxygen - (see Question 17 in the FAQ for an example)

Doxygen is not limited to Objective-C; it supports a wide range of languages, including C, C ++, and Java. Doxygen is also not limited to the Mac platform, for example. It also works on Windows and Linux. Doxygen's output also supports more than just HTML; you can create PDF output (via LaTeX) or RTF and man pages.

Doxygen also goes beyond pure documentation; doxygen can create various graphs and charts from the source code (see dot related parameters). Doxygen can also create an overview and syntax highlighted version of your code and cross-reference documentation (see source browser ).

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

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

The development of doxigen is highly dependent on user feedback. We have an active mailing list for questions and discussions and an error tracker for both errors and feature requests.

Most doxygen users use it for C and C ++ code, so naturally, these languages ​​have the most mature support, and the result is more tuned to the functions and needs for these languages. However, wishes and problems with other languages ​​are also taken seriously.

Please note that I do almost all doxygen developments and most tests on Mac.

Answer 2

I am the author of appledoc, so this answer may be biased :) I tried all the generators mentioned, although (and more), but disappointed, since none of them gave the results that I wanted to have (similar goals like you).

According to your points (I only mention appledoc and doxygen, I don't remember headerdoc very well):

• Consistent view: appledoc out of the box, the other one needs to configure css, but probably doable.

• Generation of documentation sets (for Xcode links): full support for fully searchable and selectable documentation, doxygen generates xml and makefile, which you must call yourself. In addition, appledoc supports published docset out of the box.

• Categories: appledoc allows you to combine categories with well-known classes or leave them separate, the base and other categories of the Apple class are listed separately in the index file . doxygen: this did not work when I tried.

• Custom man pages: appledoc supports out of the box, using either markdowns or custom html, doxygen: you can enable user documentation in the main page, I don’t know if you can add more pages.

• Simple command line: it depends on how you look at it: appledoc can take all arguments using command line switches (but also supports additional plist files for global and projects), so it is very easy to integrate with build scripts. doxygen requires the use of a configuration file to configure all parameters.

• Large codebases: all tools should support this, although time has not been compared. Also not sure if any tool supports cached values ​​(performed on previously collected data in order to save some time). I am studying adding this for the next major version.

It's been a while since I tried using other tools, so the above issues with doxygen / headerdoc may have been addressed! Appledoc itself also has drawbacks: as you mention, there is no support for enumerations, structures, functions, etc. (some work has been done in this direction, check this plug ), and he has his own set of problems that may prevent you from using it, depending on your requirements.

I am currently working on a major update that covers the most egregious issues , including support for enums, structures, etc. I regularly put forward new material for the experimental branch as soon as I finish the big pieces and make it stable enough so you can follow the progress. But it is still very early, and progress depends on my time, so it may take some time before a working solution.

Answer 3

Xcode 5 will now analyze your comments to find the documentation and display it:

You no longer need to use appledoc or doxygen (at least when you don't want to export your documents). More information can be found here.