一,准備工作
1,首先介紹一款VS的代碼注釋插件GhostDoc
你也許認為我們在代碼中敲入///就能自動生成xml注釋,但這種注釋是沒有說明文字的。而GhostDoc可以生成一些簡單的說明文字,如果你的函數命名很規范的話,它生成的函數描述會很准確。並且它還能生成一些參數類型的附加說明。在你想生成代碼注釋的地方按下Ctrl+Shift+D,它就會自動幫你生成xml注釋,非常方便。
下載地址:http://submain.com/products/ghostdoc.aspx
GhostDoc畢竟是個免費版,功能也有限,作為程序員有必要掌握一些常用的用於生成xml注釋的標簽。
可以參考園子里的這篇文章,寫的很好 http://www.cnblogs.com/zhangziqiu/archive/2009/01/23/1380416.html
2,在VS中生成幫助文檔的xml文件
如果是C#的工程,需要把工程的Property-->Build-->Xml Document Fiel選中,並為生成的xml文件取一個名字,
這樣,我們編譯的時候,就會自動生成代碼注釋xml文件了。需要注意一點,三個/的注釋才會生成,兩個/的注釋是不會生成的。
3,下載幫助文檔的生成工具
以前微軟維護了一個叫Sandcastle的生成工具,被認為是NDoc的繼承者。不過現在Sandcastle已經停止維護了,被移交到了這里
http://shfb.codeplex.com/ 由另外一個牛人進行維護,命名為Sandcastle Help File Builder,大家可以去下載這個工具。
下面我們就用最新的Sandcastle Help File Builder來制作一個簡單的幫助文檔。
二,制作幫助文檔
1,在開始菜單中打開Sandcastle Help File Builder GUI這個軟件,生成一個新工程。
2,導入我們的xml和對應的dll或exe文件
找到最右邊的Project Explorer-->Documentation source,點右鍵,可以添加對應的帶有注釋的xml文件,添加xml文件的同時,會把同名的dll或exe文件一並導入。
但是我們也可以選擇導入工程文件(.csproj),這樣生成幫助文檔的過程中,用到其他參照的dll會自動解決,省去了很多的麻煩。
我第一次用的是選dll這種方式,結果發現一些參照dll找不到,導致生成不成功,然后采用選擇工程文件這種方式一切就OK了。
3,導入必要的文件后,我們還需要對要生成的chm文件做一些設置。
4,查看生成的chm文件
默認的生成文件放在了My Document下面。比如我生成的文件放在了My Document-->Help-->MyFirstHelperFile.chm位置 。
下面的圖對應於上圖中每個設置部分的作用效果。
到此,一個簡單的chm幫助文件就做好了。這個工具還可以添加一些額外的圖片,txt,html等內容一起生成更加豐富的chm文件。
由於我目前用不到這些功能,沒有進一步研究