.NET中的XML代碼註釋

Question

您在代碼文件中使用了多少XML註釋，以及如何使用它們？我已經看到你可以使用它們來生成XML文檔，但是這個XML文檔可以用來爲你的代碼生成一個HTML幫助文件或模式文件嗎？

此外，您是否使用過任何自動生成的評論工具（即GhostDoc），以及您的印象如何？

想法？

Answer 1

XML本身的文件可能是有用的。這樣，API的任何使用者都可以從IDE中獲得有用的信息（通過Intellisense或對象瀏覽器）。

現在也許最大程度地使用XML註釋是從這些構建的XML文件生成幫助文檔。 Microsoft Sandcastle是目前關於此的方法。它可以生成HTML幫助1（即CHM）文件或HTML幫助2（即可以集成到Visual Studio幫助中的幫助文件）。 （注意：過去，NDoc的選項似乎更具吸引力 - 有些人仍在使用它 - 但Sandcastle似乎是目前官方推薦的方法，尤其是考慮到它相當穩定和完整，幾乎可以滿足任何需求）請參閱SandcastleDocs網站開始（我相信這是由微軟的一位開發人員非正式組合的）。特別是，你會想看看Sandcastle Help File Builder的GUI - 以我的經驗，我發現它是一個很好的工具。

Answer 2

是的！我使用它們，並且這是所有項目的一項要求，我們將其納入其中。至於細節的級別，它取決於代碼的目的。至少所有參數和公共方法都會有摘要信息。複雜的項目通常具有代碼示例，並且記錄所有特別拋出的異常。

現在我正在使用SandCastle來完成文檔構建，並且您可以在沒有任何問題的情況下轉到HTML或CHM！我還使用了SlickEdit，它可以快速解析，並且它也很棒！

Answer 3

是的，我確實使用這個功能，並認爲這是所有開發者評論他們的api的好習慣。一旦你爲幾個apis完成了這個任務，並且只要你保持最佳狀態，那麼維護它並不難。

選項1：SandCastle 我試過使用這個，但是我發現有太多的安裝程序需要運行，安裝和學習配置。最後，我最終得到了一個chm文件，但是我真的想要更輕一點的東西。

好處是最終產品看起來非常專業。儘管如此，它並不適合我的情況。

選項2：NDoc 我上次檢查時，這個項目沒有被維護，只能用於.NET的1.1版本。

方案3：XSLT 有人在CodeProject上寫了XSLT文件中查找該

http://www.codeproject.com/KB/XML/XMLDocStylesheet.aspx

我試了一下，在這裏是如何工作的。 構建您的項目並將xslt文件放入與輸出的xml文件相同的目錄中。雙擊XML文件時，將顯示一個格式化的網頁，而不是xml文檔。

對我來說，這是最好的選擇。

Answer 4

至少我包含公共API的註釋並生成xml文件。這足以讓智能感知工作，並且它也出現在Reflector中。

就個人而言，我不打擾sandcastle等 - 但我可能爲ISV項目。

Answer 5

我們用XML註釋記錄所有方法和屬性。兩者都用於內部文檔目的，並且能夠爲我們的二進制文件提供幫助文件。在intellisense中彈出一個方法的文檔是非常好的。

我們使用的是GhostDoc - 它可以提供 - 通常是OK - 默認文檔，但請記住，GhostDoc只能記錄從方法和參數名稱中推斷出的內容。因此，我們的規則是您可以使用GhostDoc來啓動文檔;然後適當地編輯它 - 在許多情況下，參數的默認文檔將會很好。在簡單的情況下，我們也只是堅持使用默認文檔，如果它是有道理的。

幫助文件可以使用Sandcastle(download)生成。另外，the Sandcastle Help File Builder是一個GUI，可以讓您更輕鬆地開始使用Sandcastle。

Answer 6

我試着去做任何不明顯的方法。我喜歡它包含Intellisense中的文檔。

Answer 7

我以前使用過微軟的SandCastle工具來從Xml註釋中生成MSDN樣式文檔，並且真的很幸運。假設它是用於生成所有.net框架文檔的工具，這些文檔也恰好來自Xml註釋。如果從構建伴隨着DLL文件分發XML文件

http://msdn.microsoft.com/en-us/vstudio/bb608422.aspx

Answer 8

我正在利用NuDoc以降價格式生成靜態API網站。 API是乾淨的，現代的，非常輕巧，易於使用（如果我可以這麼說）; http://kzu.to/nudoc

它也是開源的，所以修正和改進總是受歡迎的。