C# : 操作Word文件的API - (将C# source中的xml注释转换成word文档)这篇博客将要讨论的是关于:
如何从C#的source以及注释, 生成一份Word格式的关于各个类,函数以及成员变量的说明文档.
他的大背景如下......
最近的一个项目使用C#, 分N个模块,
在项目的里程碑的时候, 日本的总公司要检查我们的成果物.
成果物包括源代码, 概要设计式样书(SD,System Design), 详细设计式样书(PD, PRogram Design), 自动化测试等等.
源代码必须要符合编码规范(每个函数都要有注释, 方法变量的命名规则等...)
这些检查都很正常, 唯独一个比较辣手,那就是PD(一份Word文档).
PD中主要分两部分, 第一部分是UML图,
要求在UML图中,必须记载每一个变量名,函数名等等, 且必须与source完全一致.
这一点好办到, 只需要使用UML工具的逆向工程从source生成UML图即可.
PD中还需要的另一部分便是: 要为每一个类, 每一个变量, 每一个方法提供一个详细的说明(包括公有的和私有的一切)
以方法为例, 要求大概形如下面这样(类, 变量, 属性等类似):
这些关于方法,变量详细的记载, 同样要求与源代码一致(包括函数名, 参数, 函数注释等等)
在第一次做成这些文档和代码的时候还好些, 我们从一个地方拷贝到另一个地方, 他们初始是一致的,
然而接下来repeat的噩梦就开始了,两边同时维护, 总有漏下的,
而且需要花费很大的时间(尤其是检查),
有些时候, 日本方面的认真程度是我们中国人无法想象的,
比如从一份上百页的文档中, 他们能挑出某一个函数参数的大小写与source不一致这样的问题.
一个check不周,就有可能指摘.
关于问题, 已经介绍了差不多,
总之, 本着DRY原则,
同时也为了保证我们的这份word文档能够忠实于我们的source,
我想做的是: 从Source自动生成这份Word文档
为此要解决两个问题
1. 从Source中拿到相应的数据
2. 将相应的数据写到Word中.
对于第一个问题,
visual studio中, [右键一个项目 -> property -> Build -> Output]处有一个叫做[XML documentation file]的选项,
勾上他之后, 在build的时候, 就会同时生成一个xml文件, 这个文件中包含各个类的方法,成员变量, 以及他们的xml注释.
关于这个问题, 还可以参考下面两个项目, 他们帮助我们生成MSDN Style的帮助文档.
Sandcastle - Documentation Compiler for Managed Class Libraries
Sandcastle Help File Builder
(我多么希望我们不需要维护这么一份word文件, 就使用上面的工具帮助我们生成MSDN Style的帮助文档就好....)
(然而总会有一些我们搞不定的人, 拥有一些和我们不同的喜好, 还好, 我们可以满足大家, 用程序生成这份文档吧....^-^)
对于第二个问题,也就是如何用程序生成这份word文档,
在网上搜了一下, 使用word画表格的例子比较少(表格多的操作都用Excel去了)
于是结合网上搜索的结果, 我写了下面的demo程序,
能够生成前面贴图效果的word文档(实际上, 前面的那个图, 就是对下面程序的输出做的一个截屏)
下面的代码只有一个函数,
在入口处设置一个断点, 边执行边看word文件的效果, 想了解word automation的,应该可以了解一个大概.
在调查的过程中, 我发现下面的三个连接提供的示例代码比较有用, 贴到下面供大家参考(第一篇讲解的尤为详细).
Word automation using C# @C#Corner
Word automation using C# @social.msdn.microsoft.com
HOW TO：利用 Visual C# .NET 使 Word 自动新建文档 @MSDN
How to automate Microsoft Word to perform Mail Merge from Visual C# @MSDN
Automating Word Tables for Data Insertion and Extraction @MSDN
如果你使用的是其他语言, 但也需要维护一份这样的word文档的话,
大都可以使用类似的方法解决,
比如如果是java, javadoc同样可以帮助我们生成xml文档(而不仅仅局限于大家熟知的html), 然后我们从这个xml文档转换成我们需要的格式.
过程中要用到JELDoclet, 详细做法参考这个链接Tip: Javadoc as XML @IBM DeveloperWorks
C#代码
