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#代碼
