Rob Williams is a probabilistic Lean coder of Java and Objective-C. Rob is a DZone MVB and is not an employee of DZone and has posted 170 posts at DZone. You can read more from them at their website. View Full User Profile

Generating Documentation with Appledoc

01.04.2013
| 1320 views |
  • submit to reddit

 Well, I had been wanting to do this for a long time. Finally did, and though there was some pain involved, the results are stupendous. So if you are doing Objective-C, by all means, go clone appledoc from github and build a target in your project and start documenting your damned code. (You don‘t like it when the stuff you use has zero doc. Oh, and for the Ruby readers who follow the credo that documentation is bad, you can stop reading now and go back to counting the pink marshmallows in in this morning‘s bowl of Lucky Charms…)

The biggest source of pain in getting this going was the fact that the documentation, yes I see the irony, is really not very good. Mind you, the documentation you need to get going with a framework is very different than what this particular framework ends up generating for you, but.. The usual complaints can be trotted out again: the getting started stuff is a hodgepodge. It doesn‘t really set you on a track. Doesn‘t explain things adequately. Like, do I want to generate a docket? What is the feed url? Where would I serve it up from? If you dig on these things, you will find answers, but it involves a lot of the usual kind of stupid piecing together of fragmentary elements of knowledge rather than a heuristically sound tour of the tool.

The other source of pain here is the fact that this project seems to bear the hallmark of being overly data-driven, in quite a needless way. Every single thing you read about it will comment on how the number and variety of arguments that you can either embed in the plist files (project/global) or pass on the command line, are towering, complex, and brittle (one of my favorite software words, since it completely undoes soft). Having cloned the source, I started looking into it, and clearly, the reasons for this are the usual thing: the internal code was not sufficiently structured to contain the complexity, so as it grew, it was all just pushed to the surface, like a rash, or a continuing bout of urticaria.

Frankly, in looking at the code a bit (not that much, I want to go back and look again), I was immediately struck again by my own feeling that Objective-C is a beautiful language to read. (Please, go ahead and laugh, make farting noises, loosen your belt a notch, whatever you have to do to contain the explosion caused by that statement…) But also, I think it seemed like the problems are rooted in something I see in code quite a bit: the basic structural idea (design pattern lover here) that the application is designed to make one thing. It‘s not really. There should probably be a big Builder pattern at the base of this thing. Maybe even one that‘s orchestrating other Builders. For instance, the code has to be parsed. This is being subbed out, but this is often done with a builder. Then the HTML is generated, and finally, there‘s potentially a docset created. Then there could be a way to simply either swap out different implementations, or skip them altogether. The code is nice, clean, readable. One dude did this thing, and he had the guts and fortitude to go back and restructure it for a 2.0 that made a huge difference, and even had a blog post about how he‘s facing the reality that he‘s going to have to take another huge axe to it. (BTW, I volunteer, and, per my prior post, I think Apple would be crazy not to buy this dude‘s company (of 1) and immediately add this to Xcode).

Meantime, here‘s my post rabbit patch, popcorn trail suggestion: go to the linked tutorial from the main page of the project (which is broken, btw), actually here it is . Follow that. You can then build your documentation and switch to the Organizer and start browsing it. Pretty damned awesome.

Published at DZone with permission of Rob Williams, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)