The history of udoc

The origin of udoc goes a long way back, to when I still was a student at the University of Trondheim, the world's first and only Quasar Toolkit user, and about to start working at Trolltech, which at the time was called Quasar Technologies (Hi Haavard) and occupied a room and a half overlooking a busy street in a rather unfashionable part of Oslo.

I wasn't very happy with the Qt documentation, which was then written using LaTeX macros and already obsolete. I was also an opinionated asshole and far too sure of myself, and I'd just learned about Donald Knuth's literate programming techniques, but I hadn't read his book. Naturally I looked at the existing litprog tools (there were quite a few) before discarding them all to write something good.

By good, I meant that it would never require anyone to keep things in sync manually — if a function was private, the documentation tool would know that from looking at the code. It would not require editing header files often, because when header files change, compiles are slow. It would generally make things easy for the programmers. It would not be a storytelling tool, it would document individual interfaces. It would not include the source code in the documentation, because in my opinion that leads to undocumented dependencies, as people notice and use random quirks. And so on.

The first version of qdoc was written in two days, just before I joined Trolltech. It was a hundred-line perl4 script. Eirik and Haavard (Trolltech founders) looked at it, looked at the result and agreed that it would be a good idea to discard their hard documentation work and start from scratch based on my ideas. (They were right, and one day, I hope that I too will be as egoless as they were.)

The second was a new perl script, this time written in perl5, which had just come out. It slowly grew, one good idea at a time, to 2500 lines of job security. The script did a magnificent job, but I'm not proud of it. Too much job security.

The others at Trolltech would occasionally suggest releasing qdoc, since it did such a good job and there was nothing free that worked as well. I refused, arguing that qdoc was unusable for strangers — when something went wrong, often I was the only person who could understand the error message. Trying to use it without access to me would be a nightmare. Trying to support qdoc via email would be a time sink.

Sirtaj S. Kang, a KDE developer, let himself be inspired by qdoc to write something similar called kdoc. I remember looking at it briefly. I don't remember much except that didn't support all the features we needed at Trolltech, and I thought it was far too flexible for my taste. (I don't want flexibility, I want a tool that does the right thing, and sometimes that means being inflexible with the developers.)

Around the same time, Dimitri van Heesch reimplemented qdoc. He saw the markup in the Qt source and wrote a C++ program, doxygen, which took the same input and produced the same output as qdoc, as far as that was possible.

Some of the documentation source code wasn't publicly accessible yet. Trolltech decided to release that source when Dimitri asked for it and there seemed to be no reasons against doing so. Here are all the hackers making that strategic decision.

Starting from right: Haavard Nord in notverymuch, Eirik Aavitsland in dark blue t-shirt, Eirik Chambe-Eng in reddish, then I biting my nails, finally Warwick Allison and Paul Olav Tvete. It's a pity my shirt isn't visible, it was fabulously colourful.

Later, Dimitri developed doxygen in a direction away from qdoc. Whereas qdoc was aimed at generating good documentation with the least possible effort, doxygen was aimed at generating the best possible documentation for a given level of effort. That may sound similar, but the difference is profound. Doxygen will produce something even if there are no documentation blocks in the source; udoc will just spew helpful messages in that case.

At Trolltech, we never used doxygen. At first because it couldn't handle our tutorial, later because of it was developing in a different direction. I suppose there were other reasons as well, but I don't remember any details.

After a while, Trolltech grew to a point where we could think about spending time on a new, maintainable, version of qdoc. Finally Jasmin Blanchette did so in C++ when he started at Trolltech. His version was a great deal better than my perl monster. It was a relief to finally kill that perl.

Jasmin's version grew a vast feature set, and eventually was released as part of Qt, in the qdoc3 directory.

A few years after I'd left Trolltech, when we started Oryx, I wrote this program, and renamed it just before releasing. It's very simple. All the features that weren't very valuable at Trolltech have been dropped from this version. Some of the valuable features have been dropped, too, such as the support for annotated example code. We don't need that at Oryx. And some of the valuable features have been improved.

So that's where we are now. One small perl script was followed by a perl monster, which in its turn was followed by four independent reimplementations.