My Boost.Process prototype is almost feature complete; the major thing that is still not included is the ability to create pipelines. I should address that as soon as possible because I'm afraid it will have some impact on the existing classes, but for now I wanted to start documenting some code. There are already 21 header files to document and doing so is by no means an easy task.

In order to document the library's API I've decided to use Doxygen, a documentation system for multiple languages including, obviously, C++. Doxygen scans your source files looking for special comments that document classes, methods and any other part of the code. Then, the comments are extracted alongside with the code structure and are used to automatically generate reference documentation in whichever format you want (HTML, LaTeX, XML, etc.).

Doxygen is widely used and nicely integrated within Boost.Build. Boost's build system automatically generates the required configuration file for Doxygen (the Doxyfile) and lets you merge the resuting files with your other BoostBook (or QuickBook) documents painlessly.

So far I like this tool very much. Keeping the documentation alongside the source code helps in keeping it consistent and makes it immediately available to the curious developer reading the code. Furthermore, it provides tags to format anything you can imagine: preconditions, postconditions, thrown exceptions, results, etc.

The results? Take a look at the Reference section in the Boost.Process' manual ;-) At the moment of this writing only the classes in the detail subdirectory are documented, which correspond to sections 5.10 through 5.13.