Those lucky enough to use Visual Studio need not work hard to document their code: Ghostdoc does it all automatically. No mental effort required.

Write a function called getBigint(), hit control-shift-d, and ghostdoc writes Gets the Bigint; write one called nextRow() and ghostdoc helpfully documents it as Nexts the row (yes, really).

The ghostdoc site shows how it's done: There's a series of rules and patterns, ghostdoc tries the patterns one by one, and when a function matches a pattern, ghostdoc rewrites the function name/arguments to a full sentence using the corresponding rule. Yes, really.

I suppose such a tool could be useful, if its patterns were good and it would apply more than one pattern. For example: Does the function take an argument which might be null? If so, the tool could look at the code, find out what happens when that argument is null, and insert a sentence saying so. That would be useful, and a good material for PhD thesis too. Although ghostdoc's users and author are, perhaps, not very PhDish.

The inverted pyramid is how journalists are taught to write typical news stories. It puts the most newsworthy information at the top, and then the remaining information follows in order of importance, with the least important at the bottom. (The quote is from Chip Scanlan.)

This is the right way to write most API documentation. (more…)

Another finding-my-thoughts posting. Documenting helps fix bugs early, but what are its companion techniques?

Polishing the code all the time. Make it look good. Beauty is truth, truth is beauty. (more…)

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.

One of udoc's problems is that its error messages arrive towards the end of the build process. Often, when fifteen executables are being built, I wait for the interesting one to be finished and immediately switch to testing it. Later on udoc delivers some useful error messages, but I'm not looking any more. (more…)

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