Visual Basic for Applications

The ideal for documentation creation

I find that the type of documentation I want to write isn't well supported by the tools I've found. In particular, I typically like to write documentation at three levels. First, there should be a high-level overview, defining the overall purpose and ideas behind a module of code. This should be followed by detailed description of every element in a source file. Finally, I'd like to provide a line-by-line commentary of each function, commenting on the particulars of its implementation. This documentation should, as necessary, include equations, diagrams, images, flow charts, videos, etc. Because code changes frequently, all code snippets or references to names within the code should be easily refreshed by applying a tool.

I see variants of this approach in use for several types of documentation. I typically write code for other programmers, rather than end users. Therefore, my "users" will be fellow programmers desiring to make use of a module I've created. For these users, a high-level explanation of a given header file followed by a description of each element of the header, provides all the information they need to make use of the module. For fellow developers, I'd like to present the same high-level overview, this time focusing of the algorithms used to implement elements declared in the header. This information naturally belongs with the source file the header accompanies. Next, a per-element detailed description of the source file might also be accompanies by a line-by-line analysis of some of the subtle portions of the code. (On a side note, I'd like to use this to develop and updated version of the PIC24 book I co-authored).

My dream implementation would be seamless: a fully-featured word-processing program in which I can type code or in-line documentation, including snippets of code in explanatory sections as necessary. All documentation would be transparently encoded in the raw source file. No such tool exists, to the best of my knowledge.

Existing tools

There's nothing new under the sun, including this idea. Its best-known formulation, Literate Programming by none other than Donald Knuth, "regards a program as a communication to human beings rather than as a set of instructions to a computer. Your program is also viewed as a hypertext document, rather like the World Wide Web." (from an associated site). While WEB (Knuth's tool) operates on Pascal to produce TeX documents, a more modern version (CWEB) applies the same process to C. The literate programming site provides additional information on these ideas; several other notable implementations (FunnelWeb, Noweb). The practical result (here's a sample of some code) is that a program is written in CWEB syntax (mixed C and TeX), then transformed to either C or TeX, making it painful (IMHO) to either write documentation or develop code! While other tools (



My favorite documentation tool, which I've used for several years, is Doxygen. It excels at extracting documentation from code and producing a polished, nicely cross-referenced result -- the middle level (describing each element) of my documentation hierarchy. However, it contains several major flaws, IMHO:

1. There's no way to directly edit the resulting documentation. I often find a typo or other small correction when browsing through the documentation, which then requires that I dig up the corresponding source, edit it, recompile the docs, and check. This discourages quick fixes.
2. Writing high-level documentation is painful; editing text then compiling reminds me of all the evils of LaTeX without any of the helpfulness of word wrapping, TexWorks docs-to-source synchronization, or quick compilation.
3. There's no way to write line-by-line commentary for a detailed look at an algorithm.
4. Including non-textual media is painful.