简介
编程时使用嵌入式文件注释是一种方便而有效的方法，因为这样的注释可以在内存里刷新。许多开发语言，比如Java和C#都支持这种功能。可惜，SQL Server不支持。
TSQLDoc是Windows的脚本解释器，可从Transact-SQL的存储过程中萃取相关元数据和内嵌注释。本文介绍用TSQLDoc为数据库的存储过程生成相应的XML注释文件，然后用XSLT将XML注释文件转换成HTML或其他格式文件。以下介绍它的使用和示例，可在文末附件下载示例源程序。
使用TSQLDoc
TSQLDoc支持单行文件注释：
文件注释 内容
#desc 存储过程的说明
#author 作者
#version 版本
#param 参数说明
在存储过程中加入适当的注释后，TSQLDoc就能取出存储过程中的注释文本和SQL-DMO(注1)用到的数据类型与参数说明。然后由VBScript的规则表达式列出Transact-SQL代码中的注释文本。TSQLDoc将根据tsqldoc.dtd(文末下载)生成相应的XML注释文件。
脚本运行
这里使用脚本和SQL Server的Pubs数据库来做说明。先要下载文末的TSQLDoc.vbs文件，并确认你的机器满足系统要求(注2)。然后在命令行运行以下脚本程序：
cscript TSQLDoc.vbs -user [your username] -pwd [your password] -db pubs -out pubs.xml
TSQLDoc将连接到本地服务器，从pubs数据库中取出相应数据建立XML文件(pubs.xml)。这个XML文件会对每个存储过程都生成一个
1<sp>元素，例如：
2
3<sp name="reptq3">
4<parameters>
5<param datatype="money" direction="in" length="8" name="@lolimit"/>
6<param datatype="money" direction="in" length="8" name="@hilimit"/>
7<param datatype="char" direction="in" length="12" name="@type"/>
8</parameters>
9</sp>
10
11现在给数据库增加一个存储过程，加入注释(注3)：
12
13CREATE PROCEDURE DocExample (@param1 INTEGER, @param2 VARCHAR(50), @param3 DATETIME, @outparam INTEGER OUTPUT)
14AS
15
16\-- #author Morten Wittrock
17\-- #version 1.0
18\-- #desc Created with the purpose of demonstrating TSQLDoc documentation comments
19
20\-- #param @param1 Contains an integer
21\-- #param @param2 Contains a string
22\-- #param @param3 Contains a date
23\-- #param @outparam Integer output parameter
24
25\-- 本例当中没有实际操作代码
26
27运行上述脚本程序，得到XML文件如下：
28
29<sp name="DocExample" version="1.0">
30<author>Morten Wittrock</author>
31<description>Created with the purpose of demonstrating TSQLDoc documentation comments</description>
32<parameters>
33<param datatype="int" direction="in" length="4" name="@param1"/>
34<description>Contains an integer</description>
35<param datatype="varchar" direction="in" length="50" name="@param2"/>
36<description>Contains a string</description>
37<param datatype="datetime" direction="in" length="8" name="@param3"/>
38<description>Contains a date</description>
39<param datatype="int" direction="inout" length="4" name="@outparam"/>
40<description>Integer output parameter</description>
41</parameters>
42</sp>
43
44
45生成HTML文本
46TSQLDoc能用XSLT将XML注释文件转换成HTML页面(或其他格式文件)。在脚本运行程序中加入相应的XSLT文件名并指定输出为HTML文件：
47cscript TSQLDoc.vbs -user [your username] -pwd [your password] -db pubs -xslt transform.xsl -out pubs.html
48
49结语
50TSQLDoc是对SQL Server进行文本注释的基本工具。希望大家修改并发展它的用途。我的建议如下：
51
52增加对数据库对象的支持，而不仅仅用于存储过程和函数注释。
53增加对表，列和视图的元数据注释。
54增加对用户函数的注释。
55对已有注释的数据库对象作出相应报告。
56
57如在我的程序中发现问题或有其他建议，请给我来信。
58
59Have fun!
60
61\--------------------------------------------------------------------
62
63注1: SQL-DMO (SQL Distributed Management Objects) 是一个对象集，使SQL Server开发者能用程序处理和管理数据库。详情可参阅附件链接。
64
65注2: 运行TSQLDoc，系统要求：
66Microsoft XML Core Services 4.0
67VBScript version 5.0 or later
68SQL-DMO (安装SQL Server时自动安装)。
69
70注3: 运行SQL Server根目录下的instpubs.sql脚本可将pubs数据库恢复原样。
71
72http://www.sqlservercentral.com/columnists/MWittrock/TSQLDoc.vbs
73
74http://www.sqlservercentral.com/columnists/MWittrock/tsqldoc.dtd
75
76http://www.sqlservercentral.com/columnists/MWittrock/transform.xsl
77
78http://www.sqlservercentral.com/articles/articleList.asp?categoryid=53</sp>