N3Roaster's Journal: Combining CWEB and Doxygen

Yesterday, an idea crossed my mind. I enjoy using CWEB when writing programs. I also like the documentation produced by Doxygen. Is it possible to write one set of source files and get the benefits of CWEB and a pretty source code narrative while also getting API reference documentation out of Doxygen? A quick search didn't get me anywhere, so I sat down and figured it out.

On the face of it, these two systems seem incompatible with each other. Doxygen won't read the source files used by CWEB. It will read the output of ctangle, but that program strips code comments which Doxygen needs. There is, however, a command available that forces text to be included in the generated source file verbatim. If the source file contains text such as:

@=//! Doxygen can see this@>

the comment will end up in the output from ctangle. Unfortunately, cweave also understands that command and will display the comment with an ugly box drawn around it. This is particularly bad with the multiple line comments common for use with Doxygen. Doxygen markup is usually not interesting to someone reading the output from cweave, so it would be better if this could just go away. If we restrict these comments to the form above, this is easy enough to do with sed:

sed 's/@=\/.*@>//g' input.w > output.w

With this, input.w can be run through ctangle to generate a source file for use with gcc and Doxygen while output.w can be run through cweave.