I need to write extensive documentation for an iOS app I helped build and I thought this would be a neat opportunity to look into creating Apple-style API docs. I’ve used Doxygen in the past but I wanted something that could generate docs that had the look and feel of Apple’s native documentation. A quick search on Stack Overflow introduced me to AppleDoc by Gentle Bytes. You can download the full source for the application from Github. If you’re somewhat comfortable on the command line you’ll find installation to be very easy. The developers provide great installation documentation in their Readme file on Github. Gentle Bytes also provides some great user documentation as well as links to tutorials on the main AppleDoc web page.
Instead of reviewing how to format and generate documentation with AppleDoc I thought I would just touch on a few thoughts I had while using the tool (version 2.0.5, build 789, commit 700b493151).
- By default, generating documentation creates and installs an Apple-style docset into your default Xcode documentation directory. This is fine but the defaults move the docset into that directory so you’ll need to play with the command line settings if you want to version control your docs to keep and distribute them with your project in their own directory. I created a gist with the command line settings I’m currently using with AppleDoc.
- You can add a build phase to your project settings to auto-generate the documentation for a specific build configuration. If the API is public I’d probably choose to only do this on Release builds. If you are using the API internally you may want to go with Ad-Hoc builds as well. On my 2011 Macbook Air the document generation went really fast. I wouldn’t want to create documentation on each build but you might not even notice the extra build-time on smaller projects.
- In my case, I wanted to generate HTML documentation to be accessed only by the developers of the project. The biggest issue I had wasn’t even related to AppleDoc. I thought Github pages would be the perfect solution for hosting the docset but it turns out that Github pages can’t be used for private repositories. For now, my plan is to keep a copy of both the generated Apple docset and HTML formats versioned in the repository. Users can then choose to install the documentation into Xcode or just launch the HTML docs from that directory. Not a big deal really but allowing private Github pages, even for a fee, would be really helpful.
- I have a number of private methods and properties defined in unnamed class extensions in implementation files that also need documentation. According to this issue there’s a bug in the current version that makes breaking these out into their own section using the @name directive fail. At the moment I’m using the @warning directive and indicating an item is private in the description of the method or property but that is less than ideal. This is flagged as a bug with a potential fix in version 3.0 of the app.
- It looks like a future version will use the #pragma mark directives to create sections in the documentation. This would be an extremely useful addition to this already fantastic app.
- The app currently doesn’t handle documenting enums, defines, and C functions. This is a known issue and at least some of these features are in the production pipeline.
Overall this is an amazing piece of software and I’ve only used a small part of its overall functionality. The developers are providing a huge service to the Apple developer community. In only one day I have already saved a ton of time writing and building documentation. If you’re currently using Doxygen or Apple’s Headerdoc you should definitely give AppleDoc a look.
This may have more to do with the SSD than the processor so YMMV. ↩
I guess it could also be hosted on a corporate intranet…does anybody even use the word intranet anymore? ↩
I also stumbled across this Stack Overflow thread where the developers of Doxygen and AppleDoc discuss the strengths and weaknesses of their respective applications. Cool stuff. ↩