黃偉榮的學習筆記

軟體的世界變化萬千,小小的我只能在這洪流奮發向上以求立足。
posts - 100, comments - 212, trackbacks - 1, articles - 0
  博客园 :: 首页 :: 新随笔 :: 联系 :: 订阅 订阅 :: 管理

使用DocProject外速產生.NET物件文件(一)

Posted on 2007-09-06 23:57 黃偉榮 阅读(...) 评论(...) 编辑 收藏

一份完整又詳細的物件文件,在團隊溝通、技術傳遞或使用上都有很大的重要性(自用也很不錯),想想一個新加入團隊或接手你工作的人,沒有文件只有看原始碼或註解去猜功能,這是多什痛苦的一件事,但寫一份物件文件在之前是非常麻煩的,而且完全沒有相輔的工具,像我最早寫物件文件,是用Word做,Class Name、Funciotn、Property等都是用複製貼上,然後加打上說明,費時又費力,而且又沒有同步功能,當纇別修改了也就只有打開來Word修改,之後為了改善這困境,找了不少軟體,像NDoc等,雖然比Word好用很多,但使用上還是很不便,而且無法自訂內容(可能是我不會用),不過現在有了DocProject作一份物件文件就不是件困難的事(僅使用上)。

DocProject是在CodePlex上的一個專案,CodePlex是學.NET必來的網站,我就是從Visual Studio Addins中找到DocProject,DocProject的使用上非常的簡單,內容編輯與設定都是圖型化,使用上非常的方便,產生的文件就像MSDN Library一樣美觀與方便閱讀,也有索引、查尋功能,實在是太好用了,經曾看過一編文章說所以Sandcastle的工具,讓他們公司原本要花好幾天的時候做文件,現在十分鐘就好了,這不是誇張,如果平實在建物件時就勤於輸入XML文件註解,產生一份完整又詳細的物件文件真的只要十分鐘,DocProject是Visual Studio 2005/2008的增益集,以專案的方式使用,也有應用視窗版,給無法使用增益集的Express使用,目前專案方式只支援C#與VB.NET,C++/CLI只能應用視窗產生(沒試過)。

DocProject 官方網站 內有豐富的說明

安裝DocProject必需需要以下軟體(官方說明)
Visual Studio 2005 with Service Pack 1
Sandcastle, June 2007 CTP 
HTML Help Workshop: Help 1.x
Visual Studio 2005 SDK: Help 2.x (可以不裝)

安裝完以上軟體在安裝 DocProject 

使用範例

建立專案與文件專案

首先新建立一個類別庫專案(DocProject也支援網站,這裡以專案作示範,應用程式專案官方說可以,但我沒成功過),專案就以平常我們使用的方式一樣,建立一些類別,打上一些XML 文件註解(如圖一)。

image

圖一 XML 文件註解

 
改變建置選項,加上XML文件檔案輸出(如圖二)(一定要勾,且XML檔名不可以改,不然我試過會錯),然後建置專案(一定要先建置,而且修改後也要建置,不然會找上一次建置的)。

image

圖二 建置選項

 

然後加入新專案,選擇DocProject範本(如圖三)

image

圖三 加入DocProject專案

 

確定會有精靈讓我們選擇些選項,第一個選項有二個選擇 Sandcastle 與 Sandcastle/Deployment(如圖四),選Sandcastle只有輸出單一個檔案,選Sandcastle/Deployment輸出單一個檔案外,還可以建立網站,供別人線上瀏覽。

image

圖四 建置類型選擇

 

再來的選項是外觀的樣式(如圖五),

image

圖五 外觀的樣式

 

再來是輸出的類型(如圖六),因為我沒有裝Visual Studio 2005 SDK: Help 2.x所以我沒辦法選Compiled Help 2.x(我覺得Help 2.x分享比較麻煩)。

image

圖六 輸出的類型

 

再來是共用的內容,大部分都可以不用改,唯一要改的只有header(如圖七),不改的話就會,每一頁的開頭都是使用預設內容(如圖八)

image

圖七 共用的內容

 

image

圖八 忘了改Header的後果

 

再來是選擇要輸出的專案(如圖九),如果忘了選專案,可以在文件專案的參考加入要輸出的專案。

image

圖九

這樣就新增完成了文件專案,如果沒有什麼要編輯的,建置文件專案就可以產出說明文件了。

 

編輯文件內容

DocProject安裝完成後會新增一個工作列(如圖十),有二個按鈕,一個是API Topic Desinger,另一個是API Topic Management,必需作用的專案在文件專案才可以使用

image

圖十

 

API Topic Desinger是共用內容的編輯器(如圖七),API Topic Management是物件內容的編輯器,這二個功能也可以從工具 > 選項 > DocProject > Active Projects 中呼叫  

API Topic Management

Topic Filter可以篩選要輸出的類別(如圖十一),篩選的選項是滿多的,依自己的情境設定,預設是輸出全部

image

圖十一

 

XML Comments是編輯物件的XML文件註解,簡易的編輯器可以輸入內容,插入圖片與排版,每一個API都有三個XML文件註解選項sumary、ramarts、example,有看過MSDN就不難猜出輸出為的位址,雖然他只有提供三個XML文件註解選項,但原始檔上的其他XML 文件註解也會輸出,如param、exception等(如圖一)。

使用API Topic Management編輯的XML文件註解,並不會修改原始檔的註解(我是希望可以覆蓋原始檔的註解),而是寫在 文件專案 > Comments > [專案名稱].XML,預設的設定是輸出時覆寫原始檔案XML文件註解,但文件專案沒有的API XML文件註解,以專案的XML文件註解輸出。


 

(未完續待....)