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 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 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 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:
- 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.
Answer
As the creator and lead developer of doxygen, let me also provide my perspective
(obviously biased as well ;-)
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.
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.
As of version 1.8.0, doxygen supports Markdown markup, as well a large number of additional markup commands.
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 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 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 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 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.
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.
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.
Note that I do nearly all doxygen development and most testing on a Mac myself.