Javadoc is built in to Java, but I think they botched it. It's clear that they didn't care deeply: JLS3 grammar doesn't mention javadoc at all, and the JLS doesn't specify it, hardly even mentions it… the word stepchild sounds more appropriate than does builtin, in my oh-so-humble opinion.

There are many things I don't like about the result, and few things I do like.

There's too much typing for not enough benefit. (more…)

The four major output formats (long print, piecemeal print, ASCII on screen and hypertext) all have their fans, all have their uses, the ideal system would support all four, but it isn't possible to support all four really well.

Writing, designing or encoding for plain ASCII just isn't the same as writing for pages. One of the books I read ages ago had a very nice example, showing two pages of text vs. one screen of text. The pages allowed boxes that didn't intrude on reading the regular text, fine graphics, and easy overview of a lot of data. In all, around six times as much information in front of the reader's eyes. (more…)

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…)

The TeXbook employs something called literate programming: Knuth wrote code and text together, effectively writing a narrative about that code, with that code as part of the narrative.

Knuth could do that, he's a genius. He was able to write a sizable program practically without bugs, in a note-book. Mortals like myself could not. I'd have to go back and rewrite earlier bits, and before long the narrative would stink. (more…)

Most people who talk about literate programming seem to care mostly about the output. The written documentation. I care more about the actual writing, and the result of the writing process.

When you write something, when you explain it, you gain a deeper insight yourself. That's a cliché, to be sure, but it can be leveraged to write better code. There are two parts to it: Helping yourself and having your tool help you. (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…)

Udoc is the name of my latest program to do literate programming, and I'm reusing it here, for writing about the subject. It is perhaps not a very good name, but I used it since the subject is such a many-faceted one:

API documentation is what I did at Trolltech. At least that's what I thought I was doing at the start. As I was developing the format and writing text, I found I could use the documentation for two other purposes:

Maintainer documentation is one half of what Abhijit and I do for Archiveopteryx.

Writing better code through writing documentation and thereby developing a better understanding.

Checking boxes is what I see much too often. There Shall Be Documentation, or I Will Document My Code; but the actual documentation is meaningless — doesn't answer any questions I have about the code or interface.

Literate programming tools can be used for all three. Some are better suited to one purpose, some to another. Disciplined usage can help reach a goal even if the program fails to help — I still think it's a failure, though.

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…)

This is a placeholder.

I'm the next many months, I'm going to write long series of semirelated postings on source code documentation, covering the techniques I developed at Trolltech and extended for Archiveopteryx, what other people are doing and what I think of it all.

This is the introduction, which I mean to revise so it points to this and that. It points to nothing yet, there being nothing it could sensibly point to.

For a long time udoc was called qdoc. Because Trolltech might want to release its qdoc (abbreviated from qt doc tool for no particularly good reason), it seemed sensible to rename this one before release. A simple matter — just step along to the next letter, I thought. But then there turned out to be something called rdoc already. And two programs called sdoc. tdoc was taken too. A few quick searches showed that there are more than 26 programs like udoc.

You can understand why I considered naming it fdoc.

This is a bit of a rant.

I claim that, for any single page in a documentation set, whether it's pages in a book, web pages on a documentation site or even unix man pages, one of these three cases holds: (more…)