Apple-Style Documentation for Your Code

It's no secret that Apple's documentation is pretty good. So good, that some developers have gone so far as to hand-edit their code's documentation so that they too can have such simple, well-organized docs.

Unfortunately, that takes far too much time, especially for medium-to-large-sized projects. For most projects, automated documentation generators are the best tool for the job. One of the most common is Doxygen. It's a pretty solid piece of software; its markup is simple and clean, and its results are pretty intuitive.

Except when it comes to Objective-C code. Doxygen started out geared towards C, C++, and some of the other "more common" languages. Eventually, it had Objective-C support kind of tacked-on. Don't get me wrong; it's still very useful, and I use it for all of my coding projects. However, its output is full of terms and organizational structures that have no place in Objective-C: things like private and protected variables are the most prominent examples. Oh, and it's kind of ugly.

That's where DoxyClean comes in. DoxyClean is a Python script which, with the help of some XSLT stylesheets, transforms Doxygen's XML output into something much more readable, parsable, and geared towards Objective-C. And, with an optional -h flag passed to the script, it will even convert the newly-transformed XML into XHTML documentation in a very similar style to Apple's own documents. Simply point DoxyClean to the directory containing Doxygen's output XML, and BAM! Fresh, clean, Apple-esque documentation!

Now, be warned, this is a very early work-in-progress, so a lot of things don't work yet (like cross-linking between classes). However, it's certainly (in my opinion) a step in the right direction. Go grab the current version at my code page, and keep an eye on this blog for updates to script!

The code is released under the MIT License, so do with it as you please. If you make any modifications that extend the functionality or fix any bugs, please email it to me, and hopefully I'll be able to incorporate it into the main script.