waffle

One of the things that scare me greatly about the current generation of development tools are how many of them are dedicated to generating completely useless, documentation-looking, tautological, disk space-wasting output that would never be of any significant help to anyone.

The default output of Doxygen, Javadoc, Headerdoc and Sandcastle — the most popular open cross-platform alternative and the sponsored alternative of the three major next generation platforms — is horrible. Really horrible. What will you see? You’ll see a verbose listing of every single piece of metadata that the generation is able to reassemble, output in several files, with the documentation itself being easily lost in the flotsam. Some are clearly worse offenders than others; Javadoc’s signal-to-noise ratio is quite good. But I wouldn’t call this documentation.

This isn’t what disturbs me most. The default setting needs to be good, but if it’s not, at least we can work around it, right? Look at the options afforded by most of these tools. You can change the font size and the base path, even the filename format. And you can apply a new coat of paint. But what you can’t do, effectively, is choose how you want to structure your documentation.

You can’t choose which way you’d list the methods. You can’t group several related classes together under hierachial sections. It’s even hard in some cases to find an appropriate lookup table to be able to link to system API type definitions. And forget about including what Apple calls “guides” – prose content explaining the concepts and describing how to use a group of classes. Doxygen lets you create pages, but that’s just a small first step – there’s no sense of hierarchy, no index, no TOC. It’s just hard to do well.

I might not be so peeved by this if it wasn’t that there’s no good niche tools to fill this gap that I’ve been able to find. What most documentation generators provide at the end of the day is nothing more than what you’ll be able to find in any competent IDE, and they don’t even generate that nicely. But hey, you can get it in #FF00FF Comic Sans, and we can render it to a PDF, and if you spend twenty minutes recompiling everything and passing a lot of bullshit to ./configure, we can also draw UML diagrams and retroactively legitimize your work as structured and well thought-out to nosy bosses.

It’s a testament to the sad state of programming that this problem isn’t better solved. Concurrency, scalability, dynamic programming with IDE support — those problems are hard. But this one’s easy. It just takes effort, and for some reason we’ve stopped just clear of a good solution, or we’ve rolled it into some big in-house system that only runs on Ubuntu Feisty after a four hour configuration session and that’s too ugly to let out anyway.