Next / Previous / Contents

4.2. Extracting documentation from source files

There are currently a number of systems for extracting information from program source files to produce documentation, controlled in part by markup inserted by the programmer. For example, in the JavaDoc system, the interfaces to such things as classes and methods can be documented using comments of a particular form, called "doc comments", inserted into a source file. The file is then processed by a program that extracts those comments and the appropriate parts of the code to produce stereotyped HTML documentation pages. Similar systems include Doxygen and Doc++. Systems like these can be made to extract quite a lot of useful information from the source files. Unfortunately, since this processing depends on the syntax of the programming language, each system works with only one or a few languages.

This approach is certainly a kind of single-sourcing, but it is not much like literate programming. As in ordinary programming, the emphasis is on the code and not the exposition. Besides, the form of the documentation that such systems produce tends to be stereotyped and at least somewhat restricted, whereas with lightweight literate programming it can be whatever we can produce with our word processor or document-production system. Other disadvantages are that, to write the "doc comments", the programmer must learn and use a markup syntax that is similar in complexity to the markup of Knuth's WEB system; in fact, the programmer might need to learn a new system and a new markup syntax for each different programming language. We believe that our approach does better at optimizing for universality, simplicity, and ease of use.