13.9.4 Literate Programming
Instead of writing code containing documentation, the literate programmer
writes documentation containing code. This approach ensures a good
documentation for a program.
For more on literate-programming, see Literate Programming.
13.9.4.1 Noweb
Preparation:
# apt-get install nowebm
References for Noweb:
This is a WEB-like literate-programming tool which is simpler while providing
extensibility and language-independence. [
67] When noweb is invoked, it writes the program
source code to the output files mentioned in the noweb file, and it writes a
TeX file for typeset documentation.
The Debian ifupdown package is a fine example.
$ apt-get source ifupdown
$ cd ifupdown*
$ make ifupdown.pdf ifupdown.ps
13.9.4.2 Doxygen
Preparation:
# apt-get install doxygen doxygen-doc doxygen-gui
References for Doxygen (created by doxygen!):
It can generate HTML, RTF, Unix manual pages, PostScript, and PDF (using LaTeX)
documentation for C++, C, Java, IDL, and to some extent PHP and C# programs.
Doxygen is compatible to JavaDoc (1.1), Qt-Doc, KDOC and was specifically
designed to be used for projects that make use of Troll Tech's Qt toolkit. It creates include
dependency graphs, collaboration diagrams, and graphical class hierarchy graphs
even for not documented programs. The output is similar to Qt's documentation.
