Qdoc misses many features Javadoc has. This is intentional — javadoc has many naïve or harmful features. Here's a braindump of the features I dropped or decided against adding.

@author is one thing Qt had, but I dropped it due to two problems. First, it misled users who used it to answer the question who should I ask about this problem?. The problem was typically about some recent change to the file, and the original author of the file was the wrong person to ask. Second, there was some reluctance within the team about editing someone else's code, which delayed bugfixes.

I didn't realize at the time, but we once had a real colour of the bikeshed discussion about who should be listed as author of some code. Other aspects of that code warranted lively discussion, but we actually talked about who should be considered its author.

Doxygen, since it started as a qdoc clone, is mostly identical with qdoc. It does support some javadoc misfeatures, but in every case you can do things the qdoc way.

Qt (qdoc) switched away from a @param-like strategy to an in-sentence tag when I observed that good function documentation doesn't explain parameters separately from the function.

Good function documentation talks about the function, and mentions all the parameters in doing so. Sometimes it also has separate paragraphs for one or more parameters, but it always mentions the parameters in the sentences that describe the function itself. Javadoc's own example talks about both name and url in the documentation for getImage(), and their @param blocks mostly repeat the earlier wording.

Javadoc's @param tag is designed for the sometimes case, whereas I changed qdoc to support the always case instead, and added a warning when you don't do what you always should. In javadoc such a warning would give too many false positives.

The same argument applies (mutatis mutandis) to @return as well. The same javadoc example applies here too.

Creation date (@since) is too simple. There is some value in knowing that a function/class was added in version x.y, but not much. Users who care have to test against the older version anyway, because quite often the function/class has been extended since @since.

Boilerplate like @since is easy to add but often not valuable enough to bother with. Well, unless you want to mask a lack of documentation with bulky boilerplate.

Javadoc's @see is called \sa in qdoc, or it was called \sa until I noticed that whenever I improved a documentation item to the point where I was happy about its quality, the \sa links became unnecessary. Qdoc added the same links on its own volition, based on the documentation text.

@deprecated has potential, but I never found a way to add such a tag that produces better results than just writing an explanation. In my opinion, the java way of doing it is more verbose than Qt's (which uses no syntax, just text), but Qt's resulting documentation is better.

@code is solved very different in qdoc: qdoc knows how to include explanatory code from real source files. Java's approach is susceptible to typoes, missing critical information and other problems like this ghastly example, while qdoc's has the virtues of always providing working, complete source code for all examples, and bidirectionally links each example to the classes and functions it uses.

@link exists in qdoc, and in udoc too, but it's hardly used. Qdoc adds sensible links automatically, so there's little point in typing manual links. The automatic links generally remain meaningful in print, too.

One final item: Included HTML. That's been added to qdoc since I left Trolltech. It can be used to get finegrained control over the HTML documentation, but IMO no documentation is so good that manual HTML work is worth doing. There's always something else that provides better results for the same amount of working time, and it complicates making good PDF files from the documentation.

Any differences not mentioned here may be unintentional, or I may have forgotten about them.

Written with doxygen. It's funny to see how early qdoc syntax is still there. Features I added because they seemed to make sense, then discarded later, when I saw they didn't carry their load.

And there they are, still in use. Maybe funny isn't the right word.

Donald Knuth invented literate programming and published the TexBook as an example. The book is great, or so I've heard from many people who've read it. So why is literate programming is practically unused today, at least the kind Knuth invented? (more…)

API documentation is a particular subclass of literate programming. What makes it special?

First, its audience is diverse. Some readers know almost as much as the maintainers about the subject, others are rank beginners. Many know quite a bit about some parts of the subject and are almost ignorant of other parts. Some readers like to point and click, others prefer dead flat trees, others again prefer on-screen plain text such as man pages (I do, because I can type much faster than I can point and click). (more…)

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. (more…)