GhostDoc的使用

GhostDoc的使用

　　一、簡介

　　GhostDoc是Visual Studio的一個免費外掛程式，可以為開發人員自動產生XML格式的注釋文檔。

　　

　　二、下載

　　需要的朋友可以去這裡下載，填個Email地址就可以下了：GhostDoc

　　

　　三、安裝

　　下載安裝完成後，可以在Visual Studio的工具菜單下找到GhostDoc的身影。

　　

　　

　　在第一次使用時，會要求設定快速鍵，預設的是Ctrl+Shift+S，如果這和你設定的快速鍵有所衝突的話，可以在選擇的下拉式清單裡另外選擇一個。

 

　　GhostDoc使用的優點自然是可以快速產生注釋，提高開發效率，但是缺點也不少，首先她產生的注釋都是英文，難免有時看的會不順眼，而且有時會無法產生準確的注釋，原因在於 GhostDoc產生注釋的品質很大程度上取決於標識符命名的品質，比如方法用Pascal命名法，變數用Camel命名法等，所以使用GhostDoc也可以變向的檢查一下你的命名是否合理，是否足夠見名之意。

 

　　如果你的類成員是用於實現介面或重寫基類的成員，GhostDoc會使用既存的文檔，不論這些介面或基類來自何處，如果沒有既存的文檔可用，GhostDoc會試著”猜測”如何為你產生注釋，當然準確性可能就要看RP了。。。

 

　　四、使用

　　1、如果無法識別出變數的名字，GhostDoc就只會產生summary的標籤，此時游標會移到空白的注釋內容上：

　　

 

　　2、有時產生的注釋會不準確，或者不符合個人的習慣：

　　

 

　　3、如果命名合理，當然還是能夠準確的產生注釋的：

　　

　　

　　五、自訂配置

　　　　除了簡單的使用之外，還可以去GhostDoc中去進行自訂配置：

　　

　　

　　配置的方法在安裝目錄下有一個GhostDoc的協助文檔，可以按照文檔進行詳細設定，這裡就簡單舉個例子好了：

　　

　　1、先說最後一個Options選項卡，因為感覺比較實用有些，這裡可以自動產生附加註釋，這裡有一個CustomText的文字框，這裡既可以輸出自己想要的注釋，也可以點擊旁邊的按鈕使用系統已定義的宏變數，如下所示：

　　

　　　　這樣產生的注釋如下：

　　

　　　　呵呵，感覺不錯。。　　

 

　　2、下面說說第一個“規則”選項卡，也是最重要的一個，這裡隨便點開一個有代表性的：

　　

　　

　　在描述可以看到這個規則會檢測返回的一個以can開頭的布爾值，下面是返回的模板和產生的summary注釋模板，這裡有著最高優先順序的會出現在第一個，如果沒有匹配第一個的就依次向下尋找。

 

　　這裡可能是配置最複雜但也需求最多的地方，就以添加一個簡單的個性方法為例吧：

　　在Methods上點擊Add，然後隨便填入一個你喜歡的名字，隨後進入Method配置：

　　

　　配置完成後，可以在下面進行個簡單的測試。

 

　　隨後進入type配置：

　　

　　需要的還可以進行參數配置，方法都是大同小異的。

 

　　隨後配置summary標籤的模板，比如：

　　

　　或者可以點擊後面的按鈕選擇系統自訂的宏。

 

　　配置好了，下面來看看結果:

　　

　　得到了我們想要的結果。。^_^

 

　　3、第二個選項卡是縮寫詞的設定，這裡指的是GhostDoc會嘗試檢測的首字母縮寫，比如BuildHtmlText()方法中的Html會被解釋成HTML，但其只自動處理輔音字幕，而其他的詞則必須在這個對話方塊選項卡的配置表進行。

　　比如：

　　

　　　　隨後在規則中添加UML，重建注釋如下：

　　

　　4、"Of the"規則：比如這裡定義了size，那麼類似"FileBufferSize"的詞就會注釋成"Size of the file buffer"，貌似俺沒有啥需要自訂的了。。。

　　5、"No the" Word：在GhostDoc建立注釋時會在標識名前建立一個the，而這個選項卡的列表中顯示的內容則不會建立，效果如下：

　　　　沒有添加規則時：

　　

　　　　添加myx進入此規則，重建注釋：

　　

　　　　這個貌似有些無關痛癢，估計也就老外也會對這個the有些在意，所以才整了這麼一個規則。。。

 

　　六、其他技巧樣本

　　GhostDoc會自動檢測到繼承和重寫的方法注釋，這也大大簡化了操作。

　　例一：繼承

 　 這裡定義一個簡單的屬性，看看注釋的效果：

　　

　　再看看重寫時注釋的效果：

　　

　　哈哈，已經可以得到我們之前注釋的內容了。。。

　　這裡需要注意的是：必須使用summary注釋標籤，簡單的 // 注釋GhostDoc是不會理睬的。。。

　　

　　例二：重寫

 　　如果你要硬說GhostDoc不能產生中文的注釋，那也是不對的，其實如果你裝的是中文版的VS，那麼完全是可以產生中文的注釋的，比如這裡我們

 繼承了System.Web.UI下面的ControlBuilder類，並準備重寫HtmlDecodeLiterals()方法，先看一下VS現在的智能提示： 

 

　　現在產生注釋，看看效果：

　  

 

 

 

 

 

 

 

 

 

 

 

 

 

　　不錯不錯，注釋非常標準，就和手寫的一模一樣的。。

 

　　好了，上面就是項目中按對GhostDoc這個Visual Studio小外掛程式使用的情況，以後要是有機會搞外包，這東西估計用途可能會更大，繼續努力吧。。。^_^

　　一、簡介

　　GhostDoc是Visual Studio的一個免費外掛程式，可以為開發人員自動產生XML格式的注釋文檔。

　　

　　二、下載

　　需要的朋友可以去這裡下載，填個Email地址就可以下了：GhostDoc

　　

　　三、安裝

　　下載安裝完成後，可以在Visual Studio的工具菜單下找到GhostDoc的身影。

　　

　　

　　在第一次使用時，會要求設定快速鍵，預設的是Ctrl+Shift+S，如果這和你設定的快速鍵有所衝突的話，可以在選擇的下拉式清單裡另外選擇一個。

 

　　GhostDoc使用的優點自然是可以快速產生注釋，提高開發效率，但是缺點也不少，首先她產生的注釋都是英文，難免有時看的會不順眼，而且有時會無法產生準確的注釋，原因在於 GhostDoc產生注釋的品質很大程度上取決於標識符命名的品質，比如方法用Pascal命名法，變數用Camel命名法等，所以使用GhostDoc也可以變向的檢查一下你的命名是否合理，是否足夠見名之意。

 

　　如果你的類成員是用於實現介面或重寫基類的成員，GhostDoc會使用既存的文檔，不論這些介面或基類來自何處，如果沒有既存的文檔可用，GhostDoc會試著”猜測”如何為你產生注釋，當然準確性可能就要看RP了。。。

 

　　四、使用

　　1、如果無法識別出變數的名字，GhostDoc就只會產生summary的標籤，此時游標會移到空白的注釋內容上：

　　

 

　　2、有時產生的注釋會不準確，或者不符合個人的習慣：

　　

 

　　3、如果命名合理，當然還是能夠準確的產生注釋的：

　　

　　

　　五、自訂配置

　　　　除了簡單的使用之外，還可以去GhostDoc中去進行自訂配置：

　　

　　

　　配置的方法在安裝目錄下有一個GhostDoc的協助文檔，可以按照文檔進行詳細設定，這裡就簡單舉個例子好了：

　　

　　1、先說最後一個Options選項卡，因為感覺比較實用有些，這裡可以自動產生附加註釋，這裡有一個CustomText的文字框，這裡既可以輸出自己想要的注釋，也可以點擊旁邊的按鈕使用系統已定義的宏變數，如下所示：

　　

　　　　這樣產生的注釋如下：

　　

　　　　呵呵，感覺不錯。。　　

 

　　2、下面說說第一個“規則”選項卡，也是最重要的一個，這裡隨便點開一個有代表性的：

　　

　　

　　在描述可以看到這個規則會檢測返回的一個以can開頭的布爾值，下面是返回的模板和產生的summary注釋模板，這裡有著最高優先順序的會出現在第一個，如果沒有匹配第一個的就依次向下尋找。

 

　　這裡可能是配置最複雜但也需求最多的地方，就以添加一個簡單的個性方法為例吧：

　　在Methods上點擊Add，然後隨便填入一個你喜歡的名字，隨後進入Method配置：

　　

　　配置完成後，可以在下面進行個簡單的測試。

 

　　隨後進入type配置：

　　

　　需要的還可以進行參數配置，方法都是大同小異的。

 

　　隨後配置summary標籤的模板，比如：

　　

　　或者可以點擊後面的按鈕選擇系統自訂的宏。

 

　　配置好了，下面來看看結果:

　　

　　得到了我們想要的結果。。^_^

 

　　3、第二個選項卡是縮寫詞的設定，這裡指的是GhostDoc會嘗試檢測的首字母縮寫，比如BuildHtmlText()方法中的Html會被解釋成HTML，但其只自動處理輔音字幕，而其他的詞則必須在這個對話方塊選項卡的配置表進行。

　　比如：

　　

　　　　隨後在規則中添加UML，重建注釋如下：

　　

　　4、"Of the"規則：比如這裡定義了size，那麼類似"FileBufferSize"的詞就會注釋成"Size of the file buffer"，貌似俺沒有啥需要自訂的了。。。

　　5、"No the" Word：在GhostDoc建立注釋時會在標識名前建立一個the，而這個選項卡的列表中顯示的內容則不會建立，效果如下：

　　　　沒有添加規則時：

　　

　　　　添加myx進入此規則，重建注釋：

　　

　　　　這個貌似有些無關痛癢，估計也就老外也會對這個the有些在意，所以才整了這麼一個規則。。。

 

　　六、其他技巧樣本

　　GhostDoc會自動檢測到繼承和重寫的方法注釋，這也大大簡化了操作。

　　例一：繼承

 　 這裡定義一個簡單的屬性，看看注釋的效果：

　　

　　再看看重寫時注釋的效果：

　　

　　哈哈，已經可以得到我們之前注釋的內容了。。。

　　這裡需要注意的是：必須使用summary注釋標籤，簡單的 // 注釋GhostDoc是不會理睬的。。。

　　

　　例二：重寫

 　　如果你要硬說GhostDoc不能產生中文的注釋，那也是不對的，其實如果你裝的是中文版的VS，那麼完全是可以產生中文的注釋的，比如這裡我們

 繼承了System.Web.UI下面的ControlBuilder類，並準備重寫HtmlDecodeLiterals()方法，先看一下VS現在的智能提示： 

 

　　現在產生注釋，看看效果：

　  

 

 

 

 

 

 

 

 

 

 

 

 

 

　　不錯不錯，注釋非常標準，就和手寫的一模一樣的。。

 

　　好了，上面就是項目中按對GhostDoc這個Visual Studio小外掛程式使用的情況，以後要是有機會搞外包，這東西估計用途可能會更大，繼續努力吧。。。^_^