Add Custom XML Documentation Capability To Your SQL Code

f you've ever worked with sophisticated database systems or large applications you've probably accumulated sizable libraries of stored procedure code. Such libraries typically hold a few hundred stored procedures, ranging from perhaps a few hundred lines of code to thousands of lines—but only minimal documentation. That's because existing database documentation generators operate at the database-object level: that is, they describe the database schema, list the table structures, and show object relationships. They do describe stored procedures, but only with a skeleton—typically just a list of parameters and their data types, and then typically include the entire source code. There is no injection of user-supplied documentation from the source file. Clearly, that is not an adequate API.

I have been described as a documentation fiend; I document extensively, from design through development, wherever I go. So I could not, of course, let this situation stand. If these SQL files were C# or Java libraries instead, it would be inconceivable not to have thoroughly documented the code using common documentation generator conventions, so that anyone could generate a complete API describing how to use the code base. For example, look at any C# API in MSDN, and you will find a description of each method and each parameter within each method, as well as sample code usage rather than source code. In C#, NDoc is commonly used for this; Java has JavaDoc, and so on.