In the past days I’ve had an interesting e-mail interaction with a appledoc 1.0 user who had trouble with extracting documentation for methods of the first named section. Whichever section he would put first, it’s methods were not extracted. It’s a strange bug I’ve never experienced before. He even sent me an example header file and it looked correct.

The problem

Thinking about how appledoc 1.0 works left very little options. Basically appledoc is just a wrapper over doxygen. It instructs doxygen to run over source code files and generate intermediate files that include parsed classes, categories, protocols, methods with related documentation. When doxygen is finished, appledoc looks at generated files, extracts information and packs it in a nice looking html and finally produces documentation set. So if doxygen fails to pick up stuff, or generated intermediate files are not written in expected format, final output is missing bits and pieces…

Finally, more or less out of curiosity, I decided to pass the file over to current appledoc v2 alpha code, just to see what happens. As methods and sections documentation wasn’t yet generated at that point, I fired it up in debugger. Checking various in-memory objects that were created in the process I noticed everything was correctly picked up. I just had to stare at the screen for a while with a big smile all over my face (as you can imagine – after months of work invested into the project).

Conclusion

I still don’t know why the documentation isn’t picked up – it might be doxygen, or some not yet experienced appledoc bug. But I’m really happy with the fact that appledoc v2 is able to chew on “problematic” source code and not choke with it… Most of the issues with appledoc were actually related to it’s connection with doxygen. A great deal of appledoc code was in fact dealing with doxygen’s lack of full objective-c support (at least not on part with other languages supported). I’m not saying doxygen is bad – I think it’s one of the best source code documentation extractors I’ve tested and I’ve been testing really a lot of them – headerdoc, robodoc, autodoc, objcdoc to name just few that I remember, until I came over to doxyclean which finally lead me to create appledoc…

The work on appledoc 2.0 is slowly but definitely progressing towards the first release. Perhaps with a pinch of irony: appledoc 2.0 is also relying on many open-source components: ddcli, Cocoa Lumberjack, ParseKit, RegexKit Lite, MGTemplateEngine. However all of these are generic components dealing with specific “low-level” stuff that’s not related with the actual objectives. On the other hand, using these allowed me to concentrate on the actual problem – creating documentation set creation utility optimized for a rather different looking, but very powerful programming language – objective-c.