c＃中的備註標記的用途是什麼？

Question

我知道備註標記用於提供有關該類的其他信息，但在懸停/調用該類時，它不會在智能感知中顯示。我想知道它在哪裏有用？

Answer 1

備註用於構建文檔文件。它們用於更詳細的評論，向「摘要」標籤添加補充信息（「摘要」標籤確實在智能感知中顯示）。

生成的文檔文件將採用XML格式。

要生成文檔文件，您需要添加「/ doc」編譯器選項。 在Visual Studio中，您可以啓用XML文檔文件的生成：

1. 右鍵點擊項目名稱 - >屬性
2. 轉到Build標籤
3. 啓用（選中），將XML文檔文件選項

Answer 2

在生成文檔時，.NET中的許多標記實際上都有效。也許，最流行的和我使用的是沙堡。

這裏是一個比較舊的博客文章討論這個話題，但你會得到點：

「我想知道使用XML代碼註釋來裝飾.NET對象的概念，大多數開發人員有實際上有兩個好處：1）當你使用對象時，它在intellisense中顯示這些信息; 2）你可以像MSDN一樣製作組件文檔。「

來源：XML Code Comments and Sandcastle, demystified!

Answer 3

這些標籤是由Visual Studio的智能感知用來給你創造，如果他們正確創建的類，功能和性能提示如下：

在C＃（以及使用Visual Studio的代碼編輯器）可以通過鍵入///（三個正斜槓而不是兩個）輕鬆完成，然後按下Return鍵。

這將創建「XML註釋」併爲您添加最常見的標籤（例如您的方法的每個參數的參數標籤）。
如果光標位於類的上方，它將創建一個<summary>標記，如果它位於方法之上，則會爲每個參數額外創建<param>標記，併爲返回值創建<returns>標記。

其他的，如<remarks>然後由智能感知建議，而光標在///評論（見下例）。據我所知，IntelliSense只使用<summary>和<param>標籤。如果這些標籤中的任何一個包含cref屬性，則可以引用其他項目（如示例中所示）。

另外，正如其他答案解釋的那樣，您可以創建一個XML文檔，該文檔可以通過使用第三方工具轉換爲超鏈接文檔或靜態html文件。

例子：

/// <summary> 
/// Description what the class does 
/// </summary> 
public class MyClass 
{ 
    /// <summary> 
    /// Description what the function does 
    /// </summary> 
    /// <param name="param1">Description what the parameter does 
    /// Optional tags inside param1: 
    /// <c></c> <code></code> <list type=""></list> <paramref name="param1"/> 
    /// <para></para> 
    /// </param> 
    /// <param name="param2">Description what the parameter does</param> 
    /// <returns>Description about the return value</returns> 
    public string MyMethod(int param1, string param2) 
    { 
     return "Some value: " + MyProperty; 
    } 

    /// <summary> 
    /// Description what the property does 
    /// </summary> 
    /// <see cref="MyMethod(int, string)"/> 
    string MyProperty { get; set; } 

    // optional tags (valid for class and methods): 

    /// <completionlist cref=""/> 
    /// <example></example> 
    /// <exception cref=""></exception> 
    /// <include file='' path='[@name=""]'/> 
    /// <permission cref=""></permission> 
    /// <remarks></remarks> 
    /// <see cref=""/> 
    /// <seealso cref=""/> 
}