Generate documentation for your FxCop rules

I must admit that I am a big fan of FxCop (or Visual Studio "Code Analysis"). I believe the power of FxCop is underestimated, and the FxCop team more than deserved the award they got.

Many organizations develop their own frameworks, to support the applications they are building, to increase the productivity of their developers, to enforce standards and reduce maintenance costs. Building custom Code Analysis rules is a powerful way to augment those frameworks. You can verify that the frameworks are used the way they are supposed to be used. And if not, you can politely assist the developer to use the framework correctly.

Developing custom Code Analysis rules is not hard at all, and you can expect some posts in the future about the subject. But first I want to talk about something else: those rules need to be documented too!

As it turns out, every rules assembly contains an XML resource with a description for all the rules in the assembly. So why would you want to duplicate that information in separate documentation? Well, for the same reasons that you want to generate proper documentation from you XML comments in C#, C++ or VB source code: make it human (=user) readable!

So I created a little tool to generate an HTML file based on the XML resource in the rules assembly. I intend to build on this in the future, but a 1.0 version is here, ready to be downloaded. To get an idea of the output it produces, here's a screen shot of the HTML for one of the standard rules assemblies (the smallest one):


Obviously, there isn't much of a point generating this for the standard rules, they're well documented in the MSDN. But this may come in handy for your own rules. Let me know if you like the idea, or which additional features you need.