Kinds of literate programming

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.

Qdoc, javadoc and many try to document APIs. The literate programming does not create a tex-like narrative about anything, instead it combines information about some interface (a class, a header file) with text(s) about that interface.

(This is a very different activity. The input is different, the output is different, the purpose is different, why is the name the same? I think because both mix code and documentation in the same source file, and that's a small enough niche in people's brains that one name is all it gets. I don't mind. I happily say i18n for l10n, I happily confuse that and which, I won't be ashamed to use the same name for every technique that mixes code and documentation.)

Qdoc also weaves code into narratives, but those narratives are not about the code: Rather, the code serves as examples for an API, and the narrative is more about the API than the code. The code woven in supports the narrative, that's all.

Udoc exists in order to write maintainer documentation. That's a bit like API documentation, but the differences are many and not fiendishly subtle. Writing for yourself, or for ten people who can ask you if the text is unclear, and who may be assumed to know the code, is very different from writing for three thousand people who cannot or will not ask you, and most of which do not know the code and do not even want to know it. Both kinds of writing employ verbs and nouns, but that doesn't make them similar.

Finally, there's my pet cause: Writing to clear one's own mind of misconceptions. Where the goal of mixing is to be more aware of the design, to correct mistakes before the code is compiled for the first time. This is a unique kind of writing: The audience is irrelevant! The output format doesn't matter at all (if it matters, it is because you want to use the text as maintainer or API documentation as well).