### Daniel Doubrovkine

aka dB., CTO at artsy.net, fun at playplay.io, NYC

# Documenting WIX Code wix

Two sprints into working on a large deployment project I had already created two big installers under which the .wxs and .wxi files were multiplying only slower than components and features in them. For instance, there’re 30 .wxi files that compose a single enterprise component installer accounting for 8 merge modules.

I knew from day one that I’ll need to document all this, so I started writing documentation at the same time as the code. Unfortunately the amount of change in the source code was discouraging - I constantly had to go back and edit documentation trying to figure out everything I had changed. This wasn’t going to scale. I needed a different solution.

Wix files are XML and we treat them as source code. They should be documented as source code!

We use Doxygen to generate source code documentation. Doxygen supports filters: command line tools invoked for every file. It looks like all I need is a preprocessor that can transform a .wxs file into doxygen documentation!

A .wixproj project consists of .wxs, .wxi and .wxl files. I chose to take a .wxs file as input, which may have a Product or Merge XML node representing a product or a merge module respectively. Each .wxs file may contain a number of defines which need to be expanded. There may be includes that reference other files that might contain more wix xml, other includes, etc.

Here’s an example:

To parse this, I wrote a quick and dirty recursive preprocessor in C# that resolves all includes, expands defines and finally processes the result into a doxygen format. I wish wix had a preprocessor built-in just like the C++ preprocessor to avoid doing all that work. At least manipulating XML in .NET is straightforward and the Regex support is rich.

The most important feature of the preprocessor is to include comments above products, components, merge modules and features. Thus you can include true doxygen text which will appear in the final documentation.

Here’s a simple wix installer.

And the output that WixDoxyFilter produces.

/*! \page upgrade_test_wxs Upgrade Test
PackageDescription
This is a test MSI to demonstrate major upgrade.
A test product feature.
A test product component.
Component guid: a847491a-6a4e-44ea-b54f-efc6126dd484

FILE_PATTERNS = *.wxs *.xsd